Recipients

Create a recipient

Create a SWIFT recipient (international wire). Note for SWIFT:

account.bank_address is REQUIRED (WIRE and SWIFT) and must be a structured object (street_name, city, state, postal_code, country; each line min 1; country exactly 2 ISO letters). For ACH / USD / INSTANT_PAY, bank_address is instead a free-text string (max 500).
Top-level email is REQUIRED for WIRE / ACH / SWIFT recipients; SWIFT additionally requires phone. Omitting account.bank_address → 400 "account.bank_address: Required".
Top-level address must also be a structured object (alpha-2 country).
account_number (SWIFT): min 4, no max, may include letters (supports IBAN). swift_code: exactly 8 or 11.
There is no holder_name field — it is silently ignored. The holder is taken from first_name / last_name (individual) or company_name (business).

See the folder description for the full per-field character limits.

POST

recipients

Create a recipient

curl --request POST \
  --url https://api.balampay.com/v1/recipients \
  --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}}",
  "first_name": "Maria",
  "last_name": "Gonzalez",
  "email": "maria@example.com",
  "phone": "+5215512345678",
  "address": {
    "street_name": "Av. Insurgentes 100",
    "city": "Mexico City",
    "state": "CDMX",
    "postal_code": "06600",
    "country": "MX"
  },
  "account": {
    "account_type": "SWIFT",
    "bank_name": "Banco de Mexico",
    "account_number": "012345678901234567",
    "swift_code": "BNMXMXMM",
    "bank_address": {
      "street_name": "Av. Reforma 1",
      "city": "Mexico City",
      "state": "CDMX",
      "postal_code": "06600",
      "country": "MX"
    }
  }
}
'

{
  "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"

Idempotency-Key

string

required

Example:

"{{idempotency_key}}"

Body

application/json

user_id

string<uuid>

required

account

object

required

Show child attributes

type

enum<string>

Available options:

individual,

business

first_name

string

middle_name

string

last_name

string

company_name

string

phone

string

Maximum string length: 16

string<email>

address

metadata

object

Show child attributes

Response

Created.

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 a recipientRetrieve 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`.

⌘I

Create a recipient

curl --request POST \
  --url https://api.balampay.com/v1/recipients \
  --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}}",
  "first_name": "Maria",
  "last_name": "Gonzalez",
  "email": "maria@example.com",
  "phone": "+5215512345678",
  "address": {
    "street_name": "Av. Insurgentes 100",
    "city": "Mexico City",
    "state": "CDMX",
    "postal_code": "06600",
    "country": "MX"
  },
  "account": {
    "account_type": "SWIFT",
    "bank_name": "Banco de Mexico",
    "account_number": "012345678901234567",
    "swift_code": "BNMXMXMM",
    "bank_address": {
      "street_name": "Av. Reforma 1",
      "city": "Mexico City",
      "state": "CDMX",
      "postal_code": "06600",
      "country": "MX"
    }
  }
}
'

{
  "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": {}
}