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
}
'{
"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"
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API key provided."
}
}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.
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
}
'{
"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"
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API key provided."
}
}Authorizations
Secret API key from Settings → Developers → API keys.
Example: Authorization: Bearer sk_test_…
Headers
Client-generated key so retries do not create duplicate payouts. Reuse the same key for the same logical send.
8 - 100Body
Id of a saved beneficiary to pay (GET /beneficiaries).
"bbd938a2-dbbe-43bf-bfb9-1c5dbe444523"
Source book currency to debit (ISO 4217 or stablecoin). May differ
from the beneficiary currency when quote_id is supplied.
"NGN"
Gross send amount in Ledger minor units (e.g. kobo, cents).
5000000
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).
"supplier_goods"
Free-text note. Required when purpose is other.
"October supplier invoice"
Optional invoice or remittance reference (business accounts).
"INV-2026-042"
Firm FX quote id from POST /fx/quotes (omit purpose, or leave empty).
Required when the beneficiary currency differs from currency.
"e6bd10ee-6e53-4aaa-9cd0-a2bb980cf73e"
Response
Payout (queued, pending_approval, or rejected)
Object type discriminator.
payout Payout id.
Lifecycle status. pending_approval means maker-checker is waiting
on a second admin in the dashboard. queued/sending are in flight.
awaiting_auth, pending_approval, queued, sending, completed, failed, cancelled, rejected, expired Source book currency that was (or will be) debited.
Gross send in Ledger minor units.
System trace / remittance reference.
Recipient beneficiary id.
Customer-visible transfer fee (partner + margin + cross-border).
Transfer fee component in minor units (same as fee for most corridors).
Corridor scheme used for the send.
Destination country (ISO 3166-1 alpha-2).
Purpose code submitted with the payout.
Human-readable purpose label.
Free-text note from the request.
Invoice or remittance reference.
Firm FX quote used when currencies differed.
Applied FX rate when cross-currency.
Currency credited to the beneficiary.
Amount the beneficiary receives, in their minor units.
Decimal places for recipient_currency.
Whether POST /payouts/{id}/cancel can still succeed.
Partner or validation failure message when status is failed/rejected.
When the send was authorised (API key or PIN).
When the payout reached a terminal success state.
Creation time (UTC).
Last status change (UTC).