Virtual Accounts

Create a virtual account

Creates a crypto US_BANK virtual account (USDT on Tron).

⚠️ bank is REQUIRED for US_BANK VAs — including crypto. Omitting it returns 400 "bank is required for US_BANK virtual accounts". (An earlier support answer that said to remove bank for crypto was incorrect.)

The bank value is environment-scoped:

Sandbox (this collection): use slovak_savings_bank (the SWIFT/crypto rail). Sending portage here returns 400 "Invalid bank" — portage is only authorized in production.
Production: the same crypto rail is portage.

bank selects the provider/rail; mode: "crypto" + destination make it a crypto VA — both are needed, they are not redundant. Note: Tron (tron) is accepted on slovak_savings_bank in sandbox even though the destination.network enum historically documented only solana | polygon.

Production variant — change one line: "bank": "portage" (everything else stays the same). slovak_savings_bank and portage are both SWIFT/crypto-capable banks; the value is just environment-scoped. Precondition: the user must be status: VERIFIED and eligible for the product.

Not-ready marker: this VA type shows account_number: null until provisioned (the "PENDING-ACT-ACCOUNT" sentinel is ACT-only). Funds-ready = account_number non-null AND != "PENDING-ACT-ACCOUNT".

POST

virtual-accounts

curl --request POST \
  --url https://api.balampay.com/v1/virtual-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Api-Version: <x-api-version>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "user_id": "{{verified_user_id}}",
  "type": "US_BANK",
  "provider": "act",
  "mode": "fiat"
}
'

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

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

required

Example:

"2026-04-14"

Idempotency-Key

string

required

Example:

"{{idempotency_key}}"

Body

application/json

The body is of type object.

Response

Success.

Get a virtual account

⌘I

curl --request POST \
  --url https://api.balampay.com/v1/virtual-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Api-Version: <x-api-version>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "user_id": "{{verified_user_id}}",
  "type": "US_BANK",
  "provider": "act",
  "mode": "fiat"
}
'

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