Payouts to banks
Send money from a customer's wallet to any Nigerian bank account. The usual flow is: list the banks, verify the destination account, then start the transfer.
List banks
GET/payout/banks
Returns the banks the active provider can pay out to. Each bank has a name and a code; pass the code as bankCode below.
{
"message": "Bank list retrieved",
"status": "OK",
"banks": [
{
"name": "Access Bank",
"code": "044"
}
]
}curl -X GET "https://usetreasurywire.com/api/v1/payout/banks" \
-H "Authorization: Bearer $TREASURYWIRE_KEY"Verify a bank account
POST/payout/verify-account
Looks up the account holder's name so you can show it to your customer before sending money.
| Body | Type | Description |
|---|---|---|
accountNumberrequired | string | The destination account number. |
bankCoderequired | string | The bank's code from the bank list. |
{
"message": "Account verified",
"status": "OK",
"accountNumber": "0690000031",
"bankCode": "044",
"accountName": "ADA OBI"
}Returns 422 if the account can't be verified.
curl -X POST "https://usetreasurywire.com/api/v1/payout/verify-account" \
-H "Authorization: Bearer $TREASURYWIRE_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountNumber": "0690000031",
"bankCode": "044"
}'Send a payout
POST/payout/transfer
Debits the customer's wallet (the amount plus any payout fee you've configured), then asks the provider to send the money. If the provider rejects the transfer, the debit is reversed automatically.
| Body | Type | Description |
|---|---|---|
ownerRefrequired | string | Whose wallet to debit. |
currencyrequired | string | Three-letter currency code. |
accountNumberrequired | string | Destination account number. |
bankCoderequired | string | Destination bank code. |
bankName | string | Recommended. Used to describe the transaction. |
accountName | string | The account holder's name, from the verify step. |
amountrequired | number | Major units, greater than 0. |
narration | string | Shown on the bank statement where the bank supports it. |
reference | string | Your idempotency reference. Always send one so a retry can't pay out twice. |
{
"message": "Transfer initiated",
"status": "OK",
"transactionId": "665f2a0b9a3b4c0012ab3501",
"reference": "wd_20260604_001",
"providerTransferId": "4829113"
}| Status | Meaning |
|---|---|
200 | Transfer initiated, or this reference was already processed. |
202 | Either the provider's answer couldn't be confirmed (status PENDING), or the business requires approval for this payout (status PENDING_APPROVAL). In both cases the amount is already debited. Do not retry with a new reference. |
404 | No wallet for this owner and currency. |
422 | Validation error, insufficient balance (amount plus fee), a failed transfer that was reversed, or no payout provider set up. |
curl -X POST "https://usetreasurywire.com/api/v1/payout/transfer" \
-H "Authorization: Bearer $TREASURYWIRE_KEY" \
-H "Content-Type: application/json" \
-d '{
"ownerRef": "cust_1001",
"currency": "NGN",
"accountNumber": "0690000031",
"bankCode": "044",
"bankName": "Access Bank",
"accountName": "ADA OBI",
"amount": 5000,
"narration": "June withdrawal",
"reference": "wd_20260604_001"
}'Reconcile payouts
POST/payout/reconcile
Checks every in-flight payout with your provider and resolves it as confirmed (the debit stands) or failed (the debit is reversed). This also runs on a schedule, so you only need to call it when you want an answer immediately.
{
"message": "Reconciliation run complete",
"status": "OK",
"confirmed": 3,
"failed": 1,
"skipped": 0,
"unresolved": 0
}curl -X POST "https://usetreasurywire.com/api/v1/payout/reconcile" \
-H "Authorization: Bearer $TREASURYWIRE_KEY"