Recipients

Get a recipient

Retrieve a single recipient (payout destination) you own, by its UUID. The response is the bare recipient object (no { message, data } wrapper).

type — "individual" or "business". Personal name/contact fields are omitted entirely when empty (rather than returned as null).
address — polymorphic: a structured object { street_name, city, state, postal_code, country } when a city is on file, otherwise a plain string, otherwise omitted. This is the recipient’s own address, distinct from the bank address inside account_details.
account_type — the rail code (uppercase), e.g. ACH, WIRE, SWIFT, INSTANT_PAY, WALLET, SPEI, PSE, BRL.
account_details — a union whose fields depend on account_type. For example: SPEI → { clabe, doc_type, doc_number, doc_country_code }; WALLET → { token, network, address }; ACH/INSTANT_PAY → { routing_number, account_number, type, bank_name, bank_address }; WIRE/SWIFT → adds swift_code and a structured bank_address. doc_type values are normalized to lowercase.
metadata — your attached key/value map (defaults to {}).

Errors: a recipient that does not exist or belongs to another client both return 404; a malformed id returns 400.

GET

recipients

{recipient_id}

Get a recipient

curl --request GET \
  --url https://api.balampay.com/v1/recipients/{recipient_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Api-Version: <x-api-version>' \
  --header 'x-api-key: <api-key>'

{
  "recipient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "<string>",
  "account_type": "<string>",
  "account_details": {},
  "created_ts": "<string>",
  "updated_ts": "<string>",
  "first_name": "<string>",
  "middle_name": "<string>",
  "last_name": "<string>",
  "company_name": "<string>",
  "phone": "<string>",
  "email": "<string>",
  "address": "<string>",
  "metadata": {}
}

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"

Path Parameters

recipient_id

string<uuid>

required

Recipient UUID.

Response

Success.

recipient_id

string<uuid>

required

type

string

required

account_type

string

required

account_details

object

required

created_ts

string

required

updated_ts

string

required

first_name

string

middle_name

string

last_name

string

company_name

string

phone

string

address

metadata

object

Show child attributes

Get client configurationFetch your own client configuration: company info, your fee schedule, your authorized banks, and your custodial wallet/vault. This is a self-service endpoint — you may only read your own record. Requesting any other client's UUID returns `403`. The response envelope is `{ success, data }`, where `data` contains a nested `client` object, optional `client_wallets` and `client_vault` objects (either may be `null` if not yet provisioned), and a top-level `authorizedBanks` array. - `client.pct_fee`, `client.fixed_fee`, `client.usd_usdc_fee` — fee values as decimal strings (`usd_usdc_fee` may be `null`). - `authorizedBanks` — the banks you may use for virtual accounts: any of `portage`, `slovak_savings_bank`, `austin_capital_trust`, `zenus` (defaults to `[]`). - `client_wallets` — your custodial wallet (`address`, `network__id`, `explorer_url`); `client_vault` — your wallet vault (`vault_id`, `name`). **Errors:** `400` for a malformed UUID; `403` when the path UUID is not your own; `404` when the client record is not found. **Example response (200):** ```json { "success": true, "data": { "client": { "id": 42, "client_uuid": "550e8400-e29b-41d4-a716-446655440000", "company_name": "Acme Payments Inc.", "pct_fee": "0.0250", "fixed_fee": "0.50", "usd_usdc_fee": "0.00", "logo_url": "https://cdn.example.com/logos/acme.png", "created_ts": "2025-03-01T12:00:00.000Z", "updated_ts": "2026-06-01T09:30:00.000Z" }, "client_wallets": { "client_uuid": "550e8400-e29b-41d4-a716-446655440000", "object": "wallet", "address": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin", "explorer_url": "https://explorer.solana.com/address/9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin", "name": "Acme Treasury Wallet", "network__id": "solana" }, "client_vault": { "vault_id": "770e8400-e29b-41d4-a716-446655440111", "object": "sub-organization", "name": "Acme Sub-Org", "type": "single" }, "authorizedBanks": [ "portage", "zenus" ] } } ```

⌘I

Get a recipient

curl --request GET \
  --url https://api.balampay.com/v1/recipients/{recipient_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Api-Version: <x-api-version>' \
  --header 'x-api-key: <api-key>'

{
  "recipient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "<string>",
  "account_type": "<string>",
  "account_details": {},
  "created_ts": "<string>",
  "updated_ts": "<string>",
  "first_name": "<string>",
  "middle_name": "<string>",
  "last_name": "<string>",
  "company_name": "<string>",
  "phone": "<string>",
  "email": "<string>",
  "address": "<string>",
  "metadata": {}
}