Create Payout

Create and authorise a send in one step. The API key replaces the workspace PIN. Requires Idempotency-Key. Cross-currency sends need quote_id from POST /fx/quotes. If maker-checker applies, status is pending_approval until a second admin approves in the dashboard.

POST /payouts

cURL

same_currency

curl --request POST \
  --url https://20b9-41-90-209-232.ngrok-free.app/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "beneficiary_id": "bbd938a2-dbbe-43bf-bfb9-1c5dbe444523",
  "currency": "NGN",
  "amount": 5000000
}
'

200

{
  "object": "payout",
  "id": "6e0e15cf-8736-44fc-bb9b-372eb7b14145",
  "status": "queued",
  "currency": "NGN",
  "amount": 5000000,
  "fee": 15000,
  "transfer_fee": 10000,
  "scheme": "ngn_bank",
  "country": "NG",
  "stan": "OUT-2610-ABCDEF12",
  "beneficiary_id": "bbd938a2-dbbe-43bf-bfb9-1c5dbe444523",
  "purpose": "supplier_goods",
  "purpose_label": "Supplier payment for goods",
  "note": "October supplier invoice",
  "invoice_ref": "INV-2026-042",
  "cancellable": false,
  "created_at": "2026-10-27T13:00:00Z",
  "updated_at": "2026-10-27T13:00:01Z",
  "authorised_at": "2026-10-27T13:00:01Z"
}

Authorizations

Authorization · string · header · required

Secret API key from Settings → Developers → API keys. Example: Authorization: Bearer sk_test_…

Headers

Idempotency-Key · string · required

Client-generated key so retries do not create duplicate payouts. Reuse the same key for the same logical send.

Required string length: 8 - 100

Body

application/json

beneficiary_id · string<uuid> · required

Id of a saved beneficiary to pay (GET /beneficiaries).

Example:

"bbd938a2-dbbe-43bf-bfb9-1c5dbe444523"

currency · string · required

Source book currency to debit (ISO 4217 or stablecoin). May differ from the beneficiary currency when quote_id is supplied.

Example:

"NGN"

amount · integer · required

Gross send amount in Ledger minor units (e.g. kobo, cents).

Example:

5000000

purpose · string

Purpose code from GET /payouts/purposes. Business workspaces cannot use family_support (personal only). Common business codes: supplier_goods, services, professional_fees, salaries, rent, other (requires note).

Example:

"supplier_goods"

note · string

Free-text note. Required when purpose is other.

Example:

"October supplier invoice"

invoice_ref · string

Optional invoice or remittance reference (business accounts).

Example:

"INV-2026-042"

quote_id · string<uuid>

Firm FX quote id from POST /fx/quotes (omit purpose, or leave empty). Required when the beneficiary currency differs from currency.

Example:

"e6bd10ee-6e53-4aaa-9cd0-a2bb980cf73e"

Response

200

application/json

Payout (queued, pending_approval, or rejected)

object · enum<string> · required

Object type discriminator.

Available options: payout

id · string<uuid> · required

Payout id.

status · enum<string> · required

Lifecycle status. pending_approval means maker-checker is waiting on a second admin in the dashboard. queued/sending are in flight.

Available options: awaiting_auth, pending_approval, queued, sending, completed, failed, cancelled, rejected, expired

currency · string · required

Source book currency that was (or will be) debited.

amount · integer · required

Gross send in Ledger minor units.

stan · string · required

System trace / remittance reference.

beneficiary_id · string<uuid> · required

Recipient beneficiary id.

fee · integer

Customer-visible transfer fee (partner + margin + cross-border).

transfer_fee · integer

Transfer fee component in minor units (same as fee for most corridors).

scheme · string

Corridor scheme used for the send.

country · string

Destination country (ISO 3166-1 alpha-2).

purpose · string

Purpose code submitted with the payout.

purpose_label · string

Human-readable purpose label.

note · string

Free-text note from the request.

invoice_ref · string

Invoice or remittance reference.

quote_id · string<uuid>

Firm FX quote used when currencies differed.

fx_rate · string

Applied FX rate when cross-currency.

recipient_currency · string

Currency credited to the beneficiary.

recipient_amount · integer

Amount the beneficiary receives, in their minor units.

recipient_scale · integer

Decimal places for recipient_currency.

cancellable · boolean

Whether POST /payouts/{id}/cancel can still succeed.

failure_reason · string

Partner or validation failure message when status is failed/rejected.

authorised_at · string<date-time>

When the send was authorised (API key or PIN).

completed_at · string<date-time>

When the payout reached a terminal success state.

created_at · string<date-time>

Creation time (UTC).

updated_at · string<date-time>

Last status change (UTC).