Skip to main content
POST
Create Payout

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.

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. 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"

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.

id
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"

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