Skip to main content
POST
/
payouts
/
banks
curl --request POST \
  --url https://api-staging.stablestack.com/api/payouts/banks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "customer_id": "85b148ab-3f6b-4d55-917f-3c8de668a48e",
  "currency": "USDC",
  "account_number": "1234567890",
  "bank_name": "United Bank for Africa",
  "bank_code": "000004",
  "amount": "100",
  "recipient_name": "John Doe",
  "recipient_currency": "NGN",
  "recipient_country": "Nigeria",
  "narration": "Salary payment - May 2026"
}
'
{
  "status": "success",
  "data": {
    "id": "f3394f78-682b-4d28-9cf6-53858fb8216f",
    "sender_wallet_id": null,
    "receiver_wallet_id": null,
    "transaction_id": "EF40X2S02U",
    "asset_code": "USDC",
    "amount": "100.00000000",
    "reference_id": "6b522909-45c9-406d-ac11-b645b79a0202",
    "status": "PROCESSING",
    "created_at": "2025-05-27T11:27:29.061Z",
    "updated_at": "2025-05-27T11:27:29.061Z",
    "crypto_transaction_id": null,
    "network": null,
    "transaction_type": "PAYOUT",
    "transaction_mode": "DEBIT",
    "exchange_rate": null,
    "withdrawal_recipient_name": "John",
    "fee": null,
    "balance": "0.00000000",
    "reason": "Withdraw to 1234567890/000004",
    "customer_id": "85b148ab-3f6b-4d55-917f-3c8de668a48e",
    "recipient_currency": "NGN",
    "recipient_country": "Nigeria",
    "bank_name": "United Bank for Africa",
    "bank_code": "000004",
    "address": null,
    "bank_account": "1234567890",
    "amount_fiat": "0.00000000",
    "fiat_reference_id": null,
    "narration": "Salary payment - May 2026",
    "transfer_type": "ach",
    "walapay_transfer_type": "LOCAL"
  }
}
Creates a withdrawal payout to a bank account. Supports both customer and merchant withdrawals.

​
Key Features:

  • Supports multiple currencies and banks
  • Handles both customer and merchant payouts
  • Includes recipient verification details

​
Request Body:

Bank Withdrawal: 
{
  "customer_id": "85b148ab-3f6b-4d55-917f-3c8de668a48e", //optional
  "currency": "USDC",
  "account_number": "1234567890",
  "bank_name": "United Bank for Africa",
  "bank_code": "000004",
  "amount": "100",
  "recipient_name": "John Doe",
  "recipient_currency": "NGN",
  "recipient_country": "Nigeria"
}

Headers

​
x-api-key
string
required

Body

application/json
​
currency
enum<string>
required
Available options:
USDC
Example:

"USDC"

​
account_number
string
required
Example:

"1234567890"

​
bank_name
string
required
Example:

"United Bank for Africa"

​
bank_code
string
required
Example:

"000004"

​
amount
string
required
Example:

"100"

​
recipient_name
string
required
Example:

"John Doe"

​
recipient_currency
enum<string>
required
Available options:
NGN,
ZAR
Example:

"NGN"

​
recipient_country
enum<string>
required
Available options:
Nigeria,
South Africa
Example:

"Nigeria"

​
payment_purpose
enum<string>
required
Available options:
CAPITAL_CONTRIBUTIONS,
CHARITABLE_CONTRIBUTIONS,
CONSULTING_FEES,
CORPORATE_TAX_PAYMENTS,
DOWN_PAYMENTS_FOR_REAL_ESTATE,
EDUCATION_FEES,
EMPLOYEE_SALARIES_OR_WAGES,
EXPENSES_REIMBURSEMENT,
GIFTS,
GOVERNMENT_GRANTS,
INCOME_TAX_PAYMENTS,
INHERITANCE_PAYMENTS,
INSURANCE_CLAIM_PAYOUTS,
INSURANCE_PREMIUM_PAYMENTS,
INVESTMENTS,
LOAN_ADVANCES,
MORTGAGE_PAYMENTS,
OTHER,
PAYMENT_FOR_GOODS_AND_SERVICES,
PERSONAL_TRANSFERS,
REAL_ESTATE_PURCHASES,
REMITTANCES,
RENT,
REPAYMENT_OF_LOANS,
ROYALTIES,
TRUST_FUND_DISTRIBUTIONS,
UTILITY_BILLS,
WELFARE_OR_BENEFITS,
WINNINGS_AND_PRIZES
Example:

"Salary payment"

​
customer_id
string<uuid> | null

Required for customer withdrawals

Example:

"85b148ab-3f6b-4d55-917f-3c8de668a48e"

​
narration
string | null

Optional note or reference for the transaction

Example:

"Salary payment - May 2026"

​
transfer_type
enum<string> | null

Required for USD payouts. Transfer rail to use.

Available options:
ach,
fed_wire,
swift
Example:

"ach"

Response

Withdrawal created successfully

​
status
string
Example:

"success"

​
data
object