Preview payout fees

post

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

Preview fees for a payout before executing it. Use this endpoint to display the fee breakdown to users before they confirm — no records, wallets, or transfers are created.

Recipient identification (one of the two is required):

recipient_id — UUID of an existing saved recipient (WIRE, SWIFT, ACH, or WALLET).
account_type — supply the rail directly (WIRE | SWIFT | WALLET | ACH) to estimate fees without a saved recipient. When account_type is WALLET and no recipient_id is provided, wallet_network and wallet_token are also required.

Supported payout modes (auto-detected from the request and the VA's mode):

Fiat-to-bank — fiat-mode VA, recipient/account_type is WIRE/SWIFT/ACH. Omit payment_instructions.
Crypto-to-bank — recipient/account_type is WIRE/SWIFT/ACH and payment_instructions is supplied. Caller funds the payout with stablecoins.
Fiat-to-crypto — fiat-mode VA, recipient/account_type is WALLET. Recipient receives stablecoins; recipient_currency in the response is USDC or USDT.

Optional create_quote — when true, the preview also reserves a quote and returns quote_id plus quote_expires_at. The quote can later be redeemed by POST /payout to lock in the previewed amount/fees/FX rate.

Only supported for US_BANK virtual accounts in active status.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

string

required

Virtual account ID

Body Params

Either recipient_id or account_type must be supplied. When account_type is WALLET and recipient_id is omitted, wallet_network and wallet_token are also required.

amount

string

required

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

recipient_id

uuid

Optional. UUID of an existing saved recipient (WIRE, SWIFT, ACH, or WALLET). If omitted, supply account_type instead to estimate fees without a saved recipient.

account_type

string

enum

Optional. Rail for the destination — used when recipient_id is not supplied so fees can be estimated against a saved-recipient-less destination. Either recipient_id or account_type must be provided.

Allowed:

wallet_network

string

enum

Blockchain network for the destination wallet. Required when account_type is WALLET and recipient_id is not supplied.

Allowed:

wallet_token

string

enum

Stablecoin the recipient will receive. Required when account_type is WALLET and recipient_id is not supplied. Note: tron does not support USDC.

Allowed:

inverse_calculation

boolean

If true, treat amount as the recipient amount and back-solve the source amount such that fees are added on top. If false or omitted, amount is the source amount and fees are deducted to compute the recipient amount.

payment_instructions

object

Include to preview a crypto-funded payout (caller will send stablecoins to a deposit address). Specifies the blockchain network and stablecoin used to fund the payout.

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 (echoed when the same request is later used to create the payout).

create_quote

boolean

If true, the preview also reserves a quote and the response includes quote_id plus quote_expires_at. The quote can be redeemed by POST /payout to lock in the previewed amount, fees, and FX rate. If omitted, no quote is reserved.

Responses

200Payout fee preview

400Bad request - validation error

401Unauthorized - invalid or missing authentication

404Resource not found