API reference
Payouts
Idempotent transfers out, with lifecycle webhooks.
POST/v1/payouts
| Field | Type | Description |
|---|---|---|
| Idempotency-Key | header | Strongly recommended. Same key → same payout, never a double send. |
| amount_minor | integer | Required. Minor units (kobo, cents). |
| currency | string | Required. Must match the beneficiary's currency. |
| beneficiary | string | Required. A saved beneficiary ID with validated bank details. |
| reference | string | Required. Appears on statements for reconciliation. |
201 Created
{
"id": "po_8f3k2m",
"status": "processing",
"fee_minor": 55000,
"disclosure": { "fee": "₦550.00 flat", "arrival": "Typically minutes" }
}Statuses: processing → completed | failed | cancelled. Failures carry a structuredfailure_code(for exampleinvalid_account_number) and the held funds return to your balance. Corridor rules apply — NGN balances can only pay Nigerian bank accounts under current licensing, and blocked corridors fail withcorridor_disabled.