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

# Beneficiaries

> Save the recipients you pay often.

A beneficiary is a saved recipient: a bank account or a mobile money wallet. Use beneficiaries as your address book.

> [!NOTE]
>
> A payout does not take a beneficiary id. When you pay a saved beneficiary, copy its details into
> the payout's `beneficiary` object. See [Payouts](/guides/payouts.md).

## Create a beneficiary

`POST /v1/beneficiaries` · needs the `beneficiaries:write` scope

**type** `string` *required*

`bank_account` or `mobile_money`.

**details** `object` *required*

The recipient's details.

**details fields**

**accountNumber** `string`

Bank account number.

**bankCode** `string`

Bank code from the [institutions list](/guides/name-check.md#list-institutions).

**bankName** `string`

Bank name, for display.

**accountName** `string`

The name on the account.

**accountHolderName** `string`

An alternative to `accountName`.

**phoneNumber** `string`

Mobile money number.

**operator** `string`

Mobile money operator.

**country** `string`

Two-letter country code.

**currency** `string`

The currency this recipient is paid in.

**metadata** `object`

Your own key-value data.

```bash cURL
curl -X POST "$PAYVE_API_URL/v1/beneficiaries" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bank_account",
    "details": {
      "accountNumber": "0123456789",
      "bankCode": "058",
      "bankName": "Guaranty Trust Bank",
      "accountName": "Ngozi Adeyemi",
      "country": "NG",
      "currency": "NGN"
    },
    "metadata": { "supplierId": "sup_204" }
  }'
```

```javascript Node
const res = await fetch(`${process.env.PAYVE_API_URL}/v1/beneficiaries`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAYVE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'bank_account',
    details: {
      accountNumber: '0123456789',
      bankCode: '058',
      bankName: 'Guaranty Trust Bank',
      accountName: 'Ngozi Adeyemi',
      country: 'NG',
      currency: 'NGN',
    },
    metadata: { supplierId: 'sup_204' },
  }),
});
const { data: beneficiary } = await res.json();
```

```python Python
import os, requests

res = requests.post(
    f"{os.environ['PAYVE_API_URL']}/v1/beneficiaries",
    headers={"x-api-key": os.environ["PAYVE_API_KEY"]},
    json={
        "type": "bank_account",
        "details": {
            "accountNumber": "0123456789",
            "bankCode": "058",
            "bankName": "Guaranty Trust Bank",
            "accountName": "Ngozi Adeyemi",
            "country": "NG",
            "currency": "NGN",
        },
        "metadata": {"supplierId": "sup_204"},
    },
)
beneficiary = res.json()["data"]
```

```json Response · 201
{
  "data": {
    "id": "ben_7d2a9f0c4e1b3865",
    "merchantId": 318,
    "type": "bank_account",
    "details": {
      "accountNumber": "0123456789",
      "bankCode": "058",
      "bankName": "Guaranty Trust Bank",
      "accountName": "Ngozi Adeyemi",
      "country": "NG",
      "currency": "NGN"
    },
    "kycStatus": "pending",
    "metadata": { "supplierId": "sup_204" },
    "createdAt": "2026-11-18T09:40:00.000Z",
    "archivedAt": null
  }
}
```

**id** `string`

The `ben_` id. Use it in beneficiary URLs.

**kycStatus** `string`

The screening status: `pending`, `needs_review` or `blocked`.

**archivedAt** `string | null`

Set when the beneficiary has been archived.

## Screening

Each new beneficiary gets a screening status in `kycStatus`.

| `kycStatus` | Meaning |
| - | - |
| `pending` | No match was found. |
| `needs_review` | Not yet confirmed clear. The beneficiary is still usable. |
| `blocked` | A confirmed match. Do not pay this recipient. |

> [!WARNING]
>
> Do not pay a beneficiary whose `kycStatus` is `blocked`.

## List, get and archive

| Request | Does |
| - | - |
| `GET /v1/beneficiaries` | Lists your active beneficiaries. |
| `GET /v1/beneficiaries/{id}` | Returns one. `404` if it is not yours. |
| `DELETE /v1/beneficiaries/{id}` | Archives one. Returns `204`. Needs `beneficiaries:write`. |

Archiving hides a beneficiary from the list. It does not affect payouts already sent.

## Pay a saved beneficiary

```javascript
const { data: saved } = await (
  await fetch(`${process.env.PAYVE_API_URL}/v1/beneficiaries/ben_7d2a9f0c4e1b3865`, {
    headers: { 'x-api-key': process.env.PAYVE_API_KEY },
  })
).json();

const payoutBody = {
  sourceCurrency: 'NGN',
  destinationCurrency: saved.details.currency,
  amount: 5000000,
  method: 'bank_transfer',
  beneficiary: {
    type: saved.type,
    accountNumber: saved.details.accountNumber,
    bankCode: saved.details.bankCode,
    holderName: saved.details.accountName,
    country: saved.details.country,
  },
};
```

> [!TIP]
>
> Run a [name check](/guides/name-check.md) before you save a new beneficiary, and store the name the
> bank returned.
