Create Payout

curl --request POST \
  --url https://api.bachs.io/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination": "pd_7Kq2mNv4XbR9dLc0",
  "amount": "5000.00",
  "reference": "payout-2026-08-07-001",
  "narration": "Invoice 1042"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    destination: 'pd_7Kq2mNv4XbR9dLc0',
    amount: '5000.00',
    reference: 'payout-2026-08-07-001',
    narration: 'Invoice 1042'
  })
};

fetch('https://api.bachs.io/v1/payouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bachs.io/v1/payouts"

payload = {
    "destination": "pd_7Kq2mNv4XbR9dLc0",
    "amount": "5000.00",
    "reference": "payout-2026-08-07-001",
    "narration": "Invoice 1042"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bachs.io/v1/payouts"

	payload := strings.NewReader("{\n  \"destination\": \"pd_7Kq2mNv4XbR9dLc0\",\n  \"amount\": \"5000.00\",\n  \"reference\": \"payout-2026-08-07-001\",\n  \"narration\": \"Invoice 1042\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "pay_4Xr9dLc0mNv7Kq2B",
  "status": "pending",
  "amount": "5000.00",
  "currency": "NGN",
  "source_currency": "NGN",
  "fee": "100.00",
  "total_debited": "5100.00",
  "destination": "pd_7Kq2mNv4XbR9dLc0",
  "reference": "payout-2026-08-07-001",
  "narration": "Invoice 1042",
  "session_id": null,
  "failure_reason": null,
  "created_at": "2026-08-07T14:30:00.000Z"
}

{
  "detail": "Invalid request parameters",
  "error_code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "amount",
      "message": "Amount must be a positive decimal string",
      "type": "value_error"
    }
  ]
}

{
  "detail": "Invalid API key",
  "error_code": "UNAUTHORIZED"
}

{
  "detail": "API key does not have permission for this operation",
  "error_code": "FORBIDDEN"
}

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND"
}

{
  "detail": "Duplicate request detected",
  "error_code": "CONFLICT"
}

{
  "detail": "Rate limit exceeded. Please retry after a few seconds.",
  "error_code": "TOO_MANY_REQUESTS"
}

{
  "detail": "An unexpected error occurred. Please try again later.",
  "error_code": "INTERNAL_SERVER_ERROR"
}

Payouts

Create Payout

Send money to a payout destination you have registered. amount is what the destination receives, and the fee is charged on top, so the balance must cover total_debited. Paying out in a different currency from the balance you are debiting omits amount and passes quote_id instead. A payout to mobile money or to a bank outside Nigeria needs the account’s name, email and address on file, or it is refused with 400 PAYOUT_RECIPIENT_INCOMPLETE, whose detail names what is missing. A connected account also needs international payouts on (400 INTERNATIONAL_PAYOUTS_NOT_ENABLED).

POST

payouts

Create Payout

curl --request POST \
  --url https://api.bachs.io/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination": "pd_7Kq2mNv4XbR9dLc0",
  "amount": "5000.00",
  "reference": "payout-2026-08-07-001",
  "narration": "Invoice 1042"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    destination: 'pd_7Kq2mNv4XbR9dLc0',
    amount: '5000.00',
    reference: 'payout-2026-08-07-001',
    narration: 'Invoice 1042'
  })
};

fetch('https://api.bachs.io/v1/payouts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bachs.io/v1/payouts"

payload = {
    "destination": "pd_7Kq2mNv4XbR9dLc0",
    "amount": "5000.00",
    "reference": "payout-2026-08-07-001",
    "narration": "Invoice 1042"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bachs.io/v1/payouts"

	payload := strings.NewReader("{\n  \"destination\": \"pd_7Kq2mNv4XbR9dLc0\",\n  \"amount\": \"5000.00\",\n  \"reference\": \"payout-2026-08-07-001\",\n  \"narration\": \"Invoice 1042\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "pay_4Xr9dLc0mNv7Kq2B",
  "status": "pending",
  "amount": "5000.00",
  "currency": "NGN",
  "source_currency": "NGN",
  "fee": "100.00",
  "total_debited": "5100.00",
  "destination": "pd_7Kq2mNv4XbR9dLc0",
  "reference": "payout-2026-08-07-001",
  "narration": "Invoice 1042",
  "session_id": null,
  "failure_reason": null,
  "created_at": "2026-08-07T14:30:00.000Z"
}

{
  "detail": "Invalid request parameters",
  "error_code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "amount",
      "message": "Amount must be a positive decimal string",
      "type": "value_error"
    }
  ]
}

{
  "detail": "Invalid API key",
  "error_code": "UNAUTHORIZED"
}

{
  "detail": "API key does not have permission for this operation",
  "error_code": "FORBIDDEN"
}

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND"
}

{
  "detail": "Duplicate request detected",
  "error_code": "CONFLICT"
}

{
  "detail": "Rate limit exceeded. Please retry after a few seconds.",
  "error_code": "TOO_MANY_REQUESTS"
}

{
  "detail": "An unexpected error occurred. Please try again later.",
  "error_code": "INTERNAL_SERVER_ERROR"
}

Authorizations

Authorization

string

header

required

Bearer token authentication. Pass your API key as Authorization: Bearer sk_.... See Authentication for keys, scopes, and sandbox vs production.

Scopes

payouts:write

Headers

Idempotency-Key

string

Recommended. If the same key is retried with an identical request body, the cached response is returned rather than sending a second payout. Retrying the same key with a different body returns 409 IDEMPOTENCY_CONFLICT.

X-Account-Id

string

Pay out on behalf of an account you own rather than your own account. The destination, balance, and payout are all scoped to that party.

Body

application/json

Send money to a registered destination. Exactly one of amount or quote_id is required, never both and never neither. amount funds a same-currency payout; quote_id funds a cross-currency payout, since the quote already fixes both sides.

destination

string

required

The ID of a payout destination belonging to your account. The destination must be usable (is_usable: true).

Example:

"pd_7Kq2mNv4XbR9dLc0"

amount

string | null

The amount the destination should receive, as a decimal string (e.g. "5000.00"), in the destination's currency. The fee is charged on top of this amount, not deducted from it. Omit when supplying quote_id.

Example:

"5000.00"

quote_id

string | null

A quote ID from Create Payout Quote. Required for cross-currency payouts, where the source currency differs from the destination's currency. Omit amount when supplying this field.

Example:

null

reference

string | null

Your own reference for this payout, up to 128 characters: letters, digits, ., - and _, with no spaces. It must be unique on your account. Sending one you have already used returns 400 with Reference already exists for this organization. Use it to find the payout later with List Payouts (GET /v1/payouts?reference=...). Omit it and the payout has none; use the payout's id to track it.

Maximum string length: 128

Example:

"payout-2026-08-07-001"

narration

string | null

A short note for the recipient's bank statement. Keep it under 15 characters, with the part that matters first, such as an invoice number. We accept up to 100 characters, but many banks show only the first few, and some show their own label instead. Spaces at the start and end are removed, and an empty value counts as not sent. Line breaks and other control characters return 400 with VALIDATION_ERROR. When you send none, bank and mobile money payouts carry Bachs Payout.

Maximum string length: 100

Example:

"Invoice 1042"

metadata

object | null

Arbitrary key-value data to attach to the payout.

Example:

null

Response

Success - Payout created

The one shape a payout has on this API, across create, retrieve and list. amount is denominated in currency; fee and total_debited are denominated in source_currency. The two differ on every cross-currency payout, so the debit side must say which one it is in. For a same-currency payout source_currency equals currency.

string

required

The payout ID. Use this to look it up with Get Payout.

Example:

"pay_4Xr9dLc0mNv7Kq2B"

status

enum<string>

required

pending: accepted and queued. processing: submitted to the payment rail. completed: delivered to the destination. failed: could not be delivered, see failure_reason.

Available options:

pending,

processing,

completed,

failed

Example:

"pending"

amount

string

required

The net amount delivered to the destination, in currency.

Example:

"5000.00"

currency

string

required

The destination's currency. amount is denominated in this currency.

Example:

"NGN"

source_currency

string | null

The currency of the balance being debited. fee and total_debited are denominated in this currency. Equal to currency for a same-currency payout; different for a cross-currency payout funded with a quote_id.

Example:

"NGN"

fee

string | null

The fee charged for this payout, in source_currency.

Example:

"100.00"

total_debited

string | null

The gross amount debited from your balance, in source_currency. Equals amount + fee only for a same-currency payout, because on a cross-currency payout amount is in a different currency, so the two do not add up.

Example:

"5100.00"

destination

string | null

The payout destination ID this payout was sent to.

Example:

"pd_7Kq2mNv4XbR9dLc0"

reference

string | null

The reference you set when you created the payout. null if you set none.

Example:

"payout-2026-08-07-001"

narration

string | null

The narration we sent with this payout: the narration you sent, or our default text when you sent none (Bachs Payout on bank and mobile money payouts). null on a crypto payout without one. The recipient's bank may show it shortened, or show its own label instead.

Example:

"Invoice 1042"

session_id

string | null

The NIP session ID of a payout to a Nigerian bank account: the ID the receiving bank uses to trace the transfer. Give it to the recipient or their bank when they ask where the money is. null until status is completed, and always null on other payout types. Payouts completed before 22 October 2026 have none.

Example:

null

failure_reason

string | null

Populated only when status is failed.

Example:

null

created_at

string<date-time> | null

ISO 8601 creation timestamp.

Example:

"2026-08-07T14:30:00.000Z"

completed_at

string<date-time> | null

ISO 8601 timestamp of when the payout reached a terminal state. null while status is pending or processing.

Example:

null

General

Checkout Sessions

Connected Accounts

Products

Subscriptions

Customers

Customer sessions

Payments

Refunds

Disputes

Payouts

Payout Destinations

Balance

Virtual accounts

Your account

Files

Media

Misc

Transfers

Persons

Platform Fees

Reference

Create Payout

Authorizations

Scopes

Headers

Body

Response