Initiate payout

post

https://api.balampay.com/sandbox/v1/virtual-accounts/{id}/payout

Send funds from a virtual account to a recipient's bank account via WIRE or SWIFT transfer. Supports two modes:

Fiat Payout (no payment_instructions):

Debits the VA balance
Queues a WIRE/SWIFT transfer to the recipient
Requires sufficient balance to cover amount + fees
Requires OTP verification: include a valid 6-digit code in the x-validation-header header (obtain via POST /verification/send)

Crypto Payout (with payment_instructions):

Generates a single-use deposit wallet address
Caller sends stablecoins to the address
System converts to USD and initiates wire transfer
supporting_documents are required
Response includes deposit_instructions with wallet address and expiration
OTP is not required

Optional quote_id — redeem a quote previously reserved via POST /payout/preview with create_quote: true. When provided, the payout uses the exact amount, fees, and FX rate locked in by the quote. The quote must belong to the same client and not be expired (default lifespan: 15 minutes) or already used. If quote_id is omitted, the payout is priced at the current rate at execution time.

Prerequisites:

Virtual account type must be US_BANK and status active
Recipient must exist (type: WIRE or SWIFT)
Mode cross-validation: fiat VA requires no payment_instructions, crypto VA requires payment_instructions

Tip: Use /payout/preview first to show fees before confirming.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

string

required

Virtual account ID

Body Params

amount

string

required

Amount to send (up to 2 decimals, must be > 0, max 999999.99)

recipient_id

uuid

required

ID of the WIRE or SWIFT recipient

quote_id

uuid

Optional. UUID of a quote previously reserved via POST /payout/preview with create_quote: true. When provided, the payout uses the exact amount, fees, and FX rate locked in by the quote. Must belong to the same client and not be expired or already used. Default quote lifespan is 15 minutes. If omitted, the payout is priced at the current rate at execution time.

payment_instructions

object

Required for crypto mode VAs, must be absent for fiat mode VAs. Specifies the blockchain network and stablecoin for funding the payout.

supporting_documents

array of objects

Required for crypto mode payouts (minimum 1 document). Optional for fiat mode. Proof of payout such as invoices.

supporting_documents

client_markup

object

Override the default client markup for this transaction. If omitted, the default markup from your fee profile is used.

extra_info

object

Optional metadata for the payout

Headers

idempotency-key

uuid

required

Unique key to ensure idempotent requests

x-validation-header

string

^\d{6}$

6-digit OTP code required for fiat (balance) payouts. Obtain by calling POST /verification/send before initiating the payout. Not required for crypto payouts (when payment_instructions is present).

Responses

201Payout created successfully

400Bad request

401Unauthorized - authentication failed or OTP verification failed

404Resource not found

409Conflict - idempotency key already used with different data

500Internal server error during OTP verification