API Reference
Create Payout [POST]

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

ParameterTypeRequiredDescription
referencestring✅Your unique reference for this payout. Sending the same reference again replays the original payout instead of creating a second one.
amountnumber✅Amount in minor units of the payout currency, i.e. what the beneficiary receives. With a quoteId it must match the quote.
customerEmailstring✅The email address of the customer associated with the transaction
descriptionstring✅Provides context or explains the intent of the transaction
beneficiaryIdstring✅ (either)UUID of an existing beneficiary. Mutually exclusive with beneficiary
beneficiaryobject✅ (either)Inline beneficiary: currency, country and a destination object using the same schema as Add Beneficiary. Mutually exclusive with beneficiaryId
quoteIdstringUUID of a payout quote from Quote. Locks the exchange rate. Omit to price at the live rate.
sourceWalletCurrencystringThe wallet to debit, e.g. USD. Defaults to your payout funding wallet.
senderNamestringName shown to the beneficiary as the sender, up to 50 characters
callbackUrlstringURL to receive the payout webhook for this transaction
receiptRefstringConditionalkey 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

Wallets/Create Payout [POST]
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:

Wallets/Create Payout to existing beneficiary [POST]
{
  "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.

FieldTypeDescription
idstringTransaction ID
referencestringYour reference
statusstringCurrent payout status, usually processing
amountstringAmount debited from the source wallet, in minor units
feestringFee charged, in minor units
ratestringExchange rate applied
sourceCurrencystringWallet debited
payoutCurrencystringCurrency the beneficiary receives
payoutAmountnumberAmount the beneficiary receives, in minor units
beneficiaryIdstringThe beneficiary paid, including one created inline
createdAtstringISO 8601 timestamp
🟢 202 - Result example
{
"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.

HTTPCodeMeaning
400VALIDATIONA field failed a business rule, such as a missing beneficiaryId and beneficiary
400INSUFFICIENT_FUNDSThe source wallet cannot cover the amount plus fee
400AMOUNT_BELOW_MINIMUMThe amount is below the corridor minimum
400BENEFICIARY_NOT_FOUNDbeneficiaryId does not belong to your company
400QUOTE_INVALIDThe quoteId is unknown or its pair or amount does not match the request
400RATE_NOT_CONFIGUREDNo rate is configured for the currency pair
400PAYOUT_DISABLEDPayouts are disabled for your company
403ACCESS_DENIEDYour company is not permitted to perform this operation
409QUOTE_CONSUMEDThe quote was already executed
410QUOTE_EXPIREDThe quote expired. Create a new one.
413VALIDATIONThe referenced receipt is larger than allowed
422BENEFICIARY_UNVERIFIEDThe inline beneficiary was created but is still being verified. Retry with the returned beneficiaryId once it is verified.
422DOCUMENT_REQUIREDThis payout needs a receipt. Pass receiptRef.