Payouts

Execute a payout

Send funds from a virtual account to a recipient. The mode is auto-detected:

Fiat payout (no payment_instructions): debits the virtual account balance and queues the outbound transfer over the recipient’s rail (WIRE or ACH). Requires sufficient balance to cover the amount plus fees, and recipient_id is required. supporting_documents (an invoice) may be attached and is surfaced to compliance, but the API does not enforce it for fiat-mode payouts.

Fiat-to-crypto payout (fiat virtual account, WALLET recipient): debits the balance and delivers stablecoins to the recipient wallet.

Crypto-funded payout (payment_instructions, or mode: "CRYPTO"): returns deposit_instructions with a single-use deposit address; you fund the payout by sending stablecoins to that address, then Kira settles and sends the outbound transfer. supporting_documents (an invoice) is required unless nature_of_payment is first_party or your account is configured to not require documents.

Pass an optional quote_id (reserved via POST .../payout/preview with create_quote: true) to execute at the locked amount, fees, and rate. Prerequisites: the virtual account must be US_BANK and have reached the active state — confirm readiness via account_number being issued (or the virtual_account.activated webhook), not status alone: on the 2026-04-14 pin an active virtual account reads status: approved (the raw active value is returned only on 2026-06-01 and later). The recipient must already exist and is scoped to your client: a payout may target any recipient belonging to the client, not only recipients of the virtual account’s owning user. Requires the Idempotency-Key header. The 201 response returns the payout with id and status: "created" (lowercase); a later GET /v1/payouts/{id} reports the same payout as CREATED.

POST

virtual-accounts

{virtual_account_id}

payout

curl --request POST \
  --url https://api.balampay.com/v1/virtual-accounts/{virtual_account_id}/payout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": "100.00",
  "recipient_id": "{{recipient_id}}"
}
'

{
  "id": "<string>",
  "virtual_account_id": "<string>",
  "recipient_id": "<string>",
  "amount": "<string>",
  "currency": "USD",
  "fees": {},
  "recipient_amount": "<string>",
  "recipient_currency": "<string>",
  "status": "created",
  "created_at": "<string>",
  "metadata": {},
  "deposit_instructions": {
    "network": "solana",
    "currency": "USDC",
    "address": "<string>",
    "expires_at": "<string>"
  }
}

{
  "code": "<string>",
  "message": "<string>",
  "error": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ],
  "details": "<array>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

Stable since 2026-04-14 — unchanged in 2026-06-01.

Authorizations

Authorization

string

header

required

Access token from POST /auth (the data.access_token value).

x-api-key

string

header

required

API key issued by Kira. Required on every request, including /auth.

Headers

X-Api-Version

string

Optional. The date-versioned API version to apply for this request (e.g. 2026-04-14). When sent it always wins, even over your pinned account default. When omitted, the API uses your account's pinned version if set, otherwise a baseline default.

Example:

"2026-06-01"

Idempotency-Key

string<uuid>

required

Example:

"{{idempotency_key}}"

Path Parameters

virtual_account_id

string<uuid>

required

Virtual account UUID.

Body

application/json

VaPayoutRequest. There is no top-level currency field.

amount

string

required

Positive USD decimal; up to 2 decimals for fiat / fiat-to-crypto, up to 8 for crypto-funded payouts.

recipient_id

string<uuid>

Required for fiat and fiat-to-crypto payouts; optional for crypto-funded payouts using mode: "CRYPTO".

mode

enum<string>

Optional. CRYPTO sources the deposit address from the virtual account's inbound config without requiring recipient_id.

Available options:

FIAT,

CRYPTO

payment_instructions

object

Present marks a crypto-funded payout. tron does not support USDC.

Show child attributes

supporting_documents

object[]

Required for payouts unless nature_of_payment is first_party or your account is configured to not require documents. At most one invoice and one other. Omit the field entirely when sending no documents — an empty array is rejected.

Required array length: 1 - 2 elements

Show child attributes

nature_of_payment

enum<string>

What the payout is for. For crypto-mode payouts, this drives the supporting_documents requirement: first_party is exempt, every other value requires a document unless your account is configured to not require them. Fiat-mode payouts do not enforce this requirement at the API layer. Persisted and echoed back on the payout detail under extra_info. Values: vendor = payment to a supplier/vendor for goods or services; pobo = payment on behalf of a third party; first_party = a transfer between accounts under the SAME legal name/owner (doc-exempt for crypto-mode payouts); spot_3p = third-party spot payment; spot_1p = first-party spot payment; related_entities = payment between entities in the same corporate group; other = any reason not covered above.

Available options:

vendor,

pobo,

first_party,

spot_3p,

spot_1p,

related_entities,

other

quote_id

string<uuid>

UUID of a quote reserved via the preview.

client_markup

object

Show child attributes

extra_info

object

Show child attributes

reference

string

Your own reference, surfaced back unchanged on the payout detail.

metadata

object

Your own key/value object.

Response

Created. Returns the payout with status created (lowercase).

For crypto-funded payouts the response includes deposit_instructions with a single-use deposit address; send the stablecoins there.

string

virtual_account_id

string

recipient_id

string

amount

string

currency

string

Always USD.

Example:

"USD"

fees

object

recipient_amount

string

recipient_currency

string

status

string

created (lowercase).

Example:

"created"

created_at

string

metadata

object

deposit_instructions

object

Present only for crypto-funded payouts.

Show child attributes

curl --request POST \
  --url https://api.balampay.com/v1/virtual-accounts/{virtual_account_id}/payout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": "100.00",
  "recipient_id": "{{recipient_id}}"
}
'

{
  "id": "<string>",
  "virtual_account_id": "<string>",
  "recipient_id": "<string>",
  "amount": "<string>",
  "currency": "USD",
  "fees": {},
  "recipient_amount": "<string>",
  "recipient_currency": "<string>",
  "status": "created",
  "created_at": "<string>",
  "metadata": {},
  "deposit_instructions": {
    "network": "solana",
    "currency": "USDC",
    "address": "<string>",
    "expires_at": "<string>"
  }
}

{
  "code": "<string>",
  "message": "<string>",
  "error": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ],
  "details": "<array>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

Authentication

Versioning

Users

Virtual Accounts

Quotations

Payouts

Recipients

Reference

RFIs

Execute a payout

Authorizations

Headers

Path Parameters

Body

Response