Create Payout
https://sandboxapi.onbrails.com/api/v2/wallets/payouts (opens in a new tab)
Execute a payout in one call. There is no finalize step: the debit is reserved and the payout is queued immediately, and the terminal status arrives on the payout webhook.
This is the recommended flow for new integrations. Lock a
Quote with purpose: "payout", then pass its
quoteId here so the rate you were shown is the rate you get. The
destination can be an existing beneficiaryId or an inline beneficiary
object, so you do not have to create a beneficiary first.
Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| reference | string | ✅ | Your unique reference for this payout. Sending the same reference again replays the original payout instead of creating a second one. |
| amount | number | ✅ | Amount in minor units of the payout currency, i.e. what the beneficiary receives. With a quoteId it must match the quote. |
| customerEmail | string | ✅ | The email address of the customer associated with the transaction |
| description | string | ✅ | Provides context or explains the intent of the transaction |
| beneficiaryId | string | ✅ (either) | UUID of an existing beneficiary. Mutually exclusive with beneficiary |
| beneficiary | object | ✅ (either) | Inline beneficiary: currency, country and a destination object using the same schema as Add Beneficiary. Mutually exclusive with beneficiaryId |
| quoteId | string | UUID of a payout quote from Quote. Locks the exchange rate. Omit to price at the live rate. | |
| sourceWalletCurrency | string | The wallet to debit, e.g. USD. Defaults to your payout funding wallet. | |
| senderName | string | Name shown to the beneficiary as the sender, up to 50 characters | |
| callbackUrl | string | URL to receive the payout webhook for this transaction | |
| receiptRef | string | Conditional | key of an uploaded invoice, contract or receipt from Upload Document. Required for business transactions (B2B, B2C, C2B). See Documents & Compliance |
Amounts are in minor units. 1,000 NGN is sent as 100000. If you pass a
quoteId, the amount and the currency pair must match the quote exactly or
the request is rejected with QUOTE_INVALID.
Request
curl --request POST \
--url https://sandboxapi.onbrails.com/api/v2/wallets/payouts \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"reference": "PAYOUT-2026-0002",
"amount": 10000000,
"quoteId": "3f1c2a7e-9b4d-4c1e-8a2f-5d6e7f8a9b0c",
"customerEmail": "youknowwho@gmail.com",
"description": "Supplier invoice 0002",
"sourceWalletCurrency": "USD",
"beneficiary": {
"currency": "NGN",
"country": "NG",
"destination": {
"type": "BANK",
"bankCode": "110072",
"bankName": "78 FINANCE COMPANY LIMITED",
"accountName": "Joe Zen",
"accountNumber": "0691110031"
}
},
"receiptRef": "documents/45422f21-9a0e-479e-9e10-615556448a78/7b1c6e2a-3f0d-4c8e-9a51-2d6f8e4b9c10.pdf"
}
'Alternatively, pay an existing beneficiary without a quote:
{
"reference": "PAYOUT-2026-0003",
"amount": 10000000,
"customerEmail": "youknowwho@gmail.com",
"description": "Supplier invoice 0003",
"beneficiaryId": "1be2b747-29e6-4fc9-88cd-0895f7e22165"
}Responses
A successful request returns 202 Accepted. The payout is queued; poll Get Transaction or wait for the webhook for the final status. All amounts in the response are in minor units.
| Field | Type | Description |
|---|---|---|
| id | string | Transaction ID |
| reference | string | Your reference |
| status | string | Current payout status, usually processing |
| amount | string | Amount debited from the source wallet, in minor units |
| fee | string | Fee charged, in minor units |
| rate | string | Exchange rate applied |
| sourceCurrency | string | Wallet debited |
| payoutCurrency | string | Currency the beneficiary receives |
| payoutAmount | number | Amount the beneficiary receives, in minor units |
| beneficiaryId | string | The beneficiary paid, including one created inline |
| createdAt | string | ISO 8601 timestamp |
{
"status": true,
"message": "payout accepted",
"data": {
"id": "e6d06d21-73c8-471b-9e5b-9171920ab4ea",
"reference": "PAYOUT-2026-0002",
"status": "processing",
"amount": "6670",
"fee": "0",
"rate": "1500",
"sourceCurrency": "USD",
"payoutCurrency": "NGN",
"payoutAmount": 10000000,
"beneficiaryId": "1be2b747-29e6-4fc9-88cd-0895f7e22165",
"createdAt": "2026-11-13T10:31:02.000Z"
}
}Error codes
Every failure carries a stable code you can branch on. Validation failures use the VALIDATION_FAILED envelope shown on the Quote page.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | VALIDATION | A field failed a business rule, such as a missing beneficiaryId and beneficiary |
| 400 | INSUFFICIENT_FUNDS | The source wallet cannot cover the amount plus fee |
| 400 | AMOUNT_BELOW_MINIMUM | The amount is below the corridor minimum |
| 400 | BENEFICIARY_NOT_FOUND | beneficiaryId does not belong to your company |
| 400 | QUOTE_INVALID | The quoteId is unknown or its pair or amount does not match the request |
| 400 | RATE_NOT_CONFIGURED | No rate is configured for the currency pair |
| 400 | PAYOUT_DISABLED | Payouts are disabled for your company |
| 403 | ACCESS_DENIED | Your company is not permitted to perform this operation |
| 409 | QUOTE_CONSUMED | The quote was already executed |
| 410 | QUOTE_EXPIRED | The quote expired. Create a new one. |
| 413 | VALIDATION | The referenced receipt is larger than allowed |
| 422 | BENEFICIARY_UNVERIFIED | The inline beneficiary was created but is still being verified. Retry with the returned beneficiaryId once it is verified. |
| 422 | DOCUMENT_REQUIRED | This payout needs a receipt. Pass receiptRef. |