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, WALLET.
account_details — a union whose fields depend on account_type. For example: WALLET → { token, network, address }; ACH → { routing_number, account_number, type, bank_name, bank_address }; WIRE → 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-key: <api-key>'

import requests

url = "https://api.balampay.com/v1/recipients/{recipient_id}"

headers = {
    "Authorization": "Bearer <token>",
    "x-api-key": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {Authorization: 'Bearer <token>', 'x-api-key': '<api-key>'}
};

fetch('https://api.balampay.com/v1/recipients/{recipient_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.balampay.com/v1/recipients/{recipient_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.balampay.com/v1/recipients/{recipient_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.balampay.com/v1/recipients/{recipient_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

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

{
  "error": "Invalid request data",
  "details": [
    {
      "path": "recipientId",
      "message": "Invalid recipient ID format",
      "code": "invalid_string"
    }
  ]
}

{
  "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 2025-01-01 — unchanged in 2026-04-14.

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-04-14"

Path Parameters

recipient_id

string<uuid>

required

Recipient UUID.

Response

Success.

recipient_id

string<uuid>

required

The recipient's UUID. Recipients are the naming outlier: this field is recipient_id, not the id used by the user and virtual-account resources — parse it by name.

type

string

required

individual or business. Determines whether the holder is first_name/last_name or company_name.

account_type

string

required

The payout rail: ACH, WIRE, or WALLET. Mirrors the account.account_type discriminator sent at create time.

account_details

object

required

Rail-specific bank or wallet details, mirroring the account object sent at create time. Read-after-write caveats: for WIRE, bank_address.state and bank_address.postal_code are silently returned as empty strings even when you sent them; and a holder_name is never stored (the holder is taken from first_name/last_name or company_name).

created_ts

string

required

Creation timestamp. Outlier format: recipients use created_ts (not the ISO-8601 created_at used by user and virtual-account resources) — do not assume it round-trips as ISO 8601.

updated_ts

string

required

Last-update timestamp. Like created_ts, this is the recipient-specific *_ts field rather than the updated_at used elsewhere.

first_name

string

Given name (individual recipients). ASCII-normalized on write — accents are transliterated and disallowed characters stripped, so the stored value may differ from what you sent.

middle_name

string

Middle name (individual recipients), when provided. ASCII-normalized on write.

last_name

string

Family name (individual recipients). ASCII-normalized on write.

company_name

string

Legal company name (business recipients).

phone

string

Contact phone for the recipient, when provided.

string

Contact email for the recipient, when provided.

address

The recipient's own address (string or structured object). This is distinct from the recipient bank's address, which lives in account_details.bank_address.

metadata

object

Your own key/value string pairs attached to the recipient.

Show child attributes

Get a recipient

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

import requests

url = "https://api.balampay.com/v1/recipients/{recipient_id}"

headers = {
    "Authorization": "Bearer <token>",
    "x-api-key": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {Authorization: 'Bearer <token>', 'x-api-key': '<api-key>'}
};

fetch('https://api.balampay.com/v1/recipients/{recipient_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.balampay.com/v1/recipients/{recipient_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.balampay.com/v1/recipients/{recipient_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.balampay.com/v1/recipients/{recipient_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

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

{
  "error": "Invalid request data",
  "details": [
    {
      "path": "recipientId",
      "message": "Invalid recipient ID format",
      "code": "invalid_string"
    }
  ]
}

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

Get a recipient

Authorizations

Headers

Path Parameters

Response