> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zennopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Beneficiaries

> Create reusable, tenant-scoped bank destinations for payouts.

## Create

```http theme={null}
POST /v1/beneficiaries
Content-Type: application/json
```

| Field                 | Type   | Required | Rules                                      |
| --------------------- | ------ | -------: | ------------------------------------------ |
| `type`                | string |       No | `bank_account`; defaults to `bank_account` |
| `name`                | string |      Yes | 1–200 characters after trimming            |
| `destination_country` | string |      Yes | Uppercase ISO 3166-1 alpha-2               |
| `currency`            | string |      Yes | Uppercase ISO 4217 alpha-3                 |
| `account_number`      | string |      Yes | 3–64 characters                            |
| `bank_code`           | string |      Yes | 1–64 characters after trimming             |

```json theme={null}
{
  "type": "bank_account",
  "name": "Example Recipient",
  "destination_country": "VN",
  "currency": "VND",
  "account_number": "1234567890",
  "bank_code": "VCB"
}
```

Response (`201 Created`):

```json theme={null}
{
  "id": "ben_...",
  "type": "bank_account",
  "name": "Example Recipient",
  "destination_country": "VN",
  "currency": "VND",
  "bank_code": "VCB",
  "account_last4": "7890",
  "created_at": "2026-09-02T12:00:00.000Z"
}
```

The full account number is never returned. Beneficiaries are isolated by the
authenticated tenant and environment. A test identifier cannot be used in
live mode, and a cross-tenant identifier is treated as invalid.

## List beneficiaries

```http theme={null}
GET /v1/beneficiaries?limit=50
```

Sign the request with your backend HMAC credential. `limit` is an integer from
1 to 100 and defaults to 50. The response is `{ "data": [...] }`; each entry
has the create-response fields plus `status` (`active` or `disabled`). This
endpoint currently returns a bounded list with no pagination cursor.

Use an active beneficiary for new payouts. Full account numbers are omitted
from both create and list responses.

## Stored or inline

`POST /v1/payouts` accepts exactly one of:

* `beneficiary_id`: reuse a stored active beneficiary; or
* `beneficiary`: send the complete object inline.

Inline destinations are fingerprinted within the tenant/environment boundary
so idempotent retries do not create duplicate beneficiary records.