Preview a payout

curl --request POST \ --url https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/payout/preview \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'x-api-key: <api-key>' \ --data ' { "amount": "1000.00", "recipient_id": "cccccccc-dddd-eeee-ffff-000000000000" } '

{ "amount": "1000.00", "currency": "USD", "fees": { "base_fees": { "bank_account_fee": "10.00", "bank_account_fee_percentage": "0.00", "fixed_fee": "0.00", "percentage_fee": "2.50", "total": "12.50" }, "client_markup": { "fixed_fee": "1.00", "percentage_fee": "0.00", "total": "1.00" }, "network_fee": "0.00", "total_fees": "13.50", "total": "13.50" }, "recipient_amount": "986.50", "recipient_currency": "USD" }

{ "code": "invalid_request", "message": "The request could not be matched to a valid route, or was malformed. Verify the path and HTTP method against the API reference. This is a routing or request error, not a credentials or signature problem." }

{ "statusCode": 404, "error": "Not Found", "message": "Virtual account 11111111-2222-3333-4444-555555555555 not found", "timestamp": "2026-09-01T12:00:00.000Z", "path": "/v1/virtual-accounts/11111111-2222-3333-4444-555555555555/payout/preview" }

Authorizations

Authorization

string

header

required

The data.access_token value from Get access token.

x-api-key

string

header

required

API key issued by Kira.

Headers

X-Api-Version

string

Version applied to this request. It wins over your account's pinned version — see Versioning.

Example:

"2026-04-14"

Path Parameters

virtual_account_id

string<uuid>

required

The account the money leaves from.

Body

application/json

Send recipient_id or account_type — at least one is required.

amount

string

required

How much to send, as a positive decimal string with up to 8 decimals. With inverse_calculation this is what the recipient should end up with instead.

recipient_id

string<uuid>

A recipient you saved earlier. Its rail and details are used for the pricing.

account_type

enum<string>

Price a rail without saving a recipient first. Ignored when you also send recipient_id, which carries its own rail.

With WALLET and no recipient_id, wallet_network and wallet_token are required too. See Recipient values.

Available options:

WIRE,

ACH,

WALLET

wallet_network

enum<string>

Chain the recipient's wallet is on. Only used with account_type: WALLET and no recipient_id.

Available options:

solana,

polygon,

tron

wallet_token

enum<string>

Token the recipient receives. Not every token works on every chain, and a pair that does not is rejected with a 400.

Available options:

USDC,

USDT

inverse_calculation

boolean

Work backwards: treat amount as what the recipient receives and return what has to leave the account. false when you omit it.

client_markup

object

Your own fees for this one payout, replacing whatever is configured on your account. fixed_fee and percentage_fee are both required once you send the object.

Show child attributes

payment_instructions

object

The token and chain you will deposit to fund the payout. Sending this makes it a crypto-funded payout.

Show child attributes

extra_info

object

Your own notes on the payout. They come back on a read.

Show child attributes

create_quote

boolean

Save the price and return a quote_id you can redeem on the payout. Without it the preview prices without holding anything.

Response

The priced payout.

The priced payout. Every amount is a decimal string.

amount

string

What leaves the account.

currency

string

Currency of amount. Always USD.

fees

object

What comes off the amount before the recipient is paid.

Show child attributes

recipient_amount

string

What the recipient ends up with.

recipient_currency

string

Currency of recipient_amount — USD on a bank payout, USDC or USDT on a wallet payout.

payment_instructions

object

The funding token and chain, echoed back. Only on a crypto-funded payout.

quote_id

string<uuid>

Send this on the payout to settle at this price. Only when you asked for a quote with create_quote.

quote_expires_at

string

When that price stops holding, as an ISO 8601 timestamp.

Across the API

Authentication

Versioning

Users

Virtual Accounts

Recipients

Quotations

Payouts

Catalogs

Authorizations

Headers

Path Parameters

Body

Response