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

# Beneficiaries

> Save a recipient once per corridor and reuse it by id when sending payouts.

A **beneficiary** is a recipient you save for one corridor (`country_code` +
`currency_code`). Instead of sending the full recipient details on every payout,
you create the beneficiary once and then reference its `beneficiary_id`.

<Note>
  Beneficiaries belong to **payouts**. Every endpoint here requires the same JWT from
  [`/api/v1/user/login`](/api-reference/login) that `sendPayoutRequest` does, and an account without
  the payout product cannot reach them. This is the opposite of [payins](/payins), which take no JWT
  at all.
</Note>

## Why use them

* **Validate early.** Per-country requirements (account formats, KYC fields) are
  checked when you create the beneficiary, not at payout time.
* **Smaller payout calls.** A payout in beneficiary mode only carries the amount.
* **Stable contract.** The fields a corridor requires are defined by PontisGlobe
  and don't change if we route through a different underlying provider.

## Lifecycle

1. **Create** — [`addBeneficiary`](/api-reference/add-beneficiary) with the
   corridor + per-country `recipient_details`. We validate the fields and
   return a `beneficiary_id`.
2. **Use** — pass that `beneficiary_id` to
   [`sendPayoutRequest`](/api-reference/send-payout) in *beneficiary mode*.
3. **Manage** — [fetch](/api-reference/get-beneficiary),
   [list](/api-reference/list-beneficiaries), [update](/api-reference/update-beneficiary) or
   [archive](/api-reference/delete-beneficiary) them.

A payout always snapshots the recipient details at the moment it is created, so
editing or archiving a beneficiary never affects payouts already in flight.

## Corridor requirements

Every corridor requires `recipient_details.name`. The remaining fields fall into
a few groups depending on the destination:

| Corridor     | Rail         | Key recipient fields                                  | Sender / beneficiary KYC      |
| ------------ | ------------ | ----------------------------------------------------- | ----------------------------- |
| `NG` / `NGN` | Bank         | `account_number`, `branch_code`                       | sender name + address         |
| `KE` / `KES` | M-PESA       | `phone_e164`                                          | —                             |
| `GH` / `GHS` | MTN          | `phone_e164`                                          | —                             |
| `TZ` / `TZS` | Mobile money | `phone_e164`, `payment_network`                       | —                             |
| `UG` / `UGX` | Mobile money | `phone_e164`, `payment_network`                       | —                             |
| `RW` / `RWF` | Mobile money | `phone_e164`, `payment_network`                       | sender name + country         |
| `SN` / `XOF` | Mobile money | `phone_e164`, `payment_network`                       | sender name + country         |
| `CM` / `XAF` | Mobile money | `phone_e164`, `payment_network`                       | —                             |
| `ZA` / `ZAR` | Bank         | `account_number`, `branch_code`, `remittance_purpose` | full sender + beneficiary KYC |
| `AU` / `AUD` | Bank (BSB)   | `account_number`, `bsb_number`, `remittance_purpose`  | sender + beneficiary address  |
| `CA` / `CAD` | Bank         | `account_number`, `transit_code`, `branch_code`       | sender details                |
| `US` / `USD` | Wire         | `account_number`, `routing_number`, bank address      | full sender + beneficiary KYC |

<Info>
  Field-level tables (types, formats, exact required flags) are returned by the validation errors on
  [`addBeneficiary`](/api-reference/add-beneficiary) and shown in the dashboard's add-beneficiary
  form. Corridors marked "Mobile money" require a `payment_network` (e.g. `VODACOM`, `MTN`,
  `AIRTEL`).
</Info>

## Security

* Beneficiaries are scoped to your account. A `beneficiary_id` from one account
  is never usable by another; lookups for an id you don't own return `404`.
* Read responses mask sensitive values (e.g. last 4 of an account number).
* Sandbox and live beneficiaries are isolated — a sandbox beneficiary cannot be
  used for a live payout.