Create Bank Withdrawal

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"
  }
}

{
  "status": "error",
  "message": "Error message",
  "code": "ERROR_CODE"
}

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"
  }
}

{
  "status": "error",
  "message": "Error message",
  "code": "ERROR_CODE"
}

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

Show child attributes

API Documentation

Customers

Wallet Assets

Wallets

Banks

Beneficiary

Payouts

Transactions

Create Bank Withdrawal

Key Features:

Request Body:

Headers

Body

Response

​Key Features:

​Request Body:

Headers

Body

Response

Key Features:

Request Body: