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

# Beneficiaries

> Save recipients once and pay them by ID.

A beneficiary is a saved recipient. Save someone's details once, keep the `externalAccountId` Tanda returns, and pay them later by sending just that ID. In the API, beneficiaries are called external accounts, which is why the endpoints live under `/api/b2b/external-accounts`.

> [!TIP]
>
> Use beneficiaries for anyone you pay more than once: staff, suppliers, agents or regular customers.

## Save a beneficiary

Call [Create beneficiary](https://api.tandapay.io/api-reference/endpoint/create-beneficiary.md) with `type: "payout"`, the destination and the payout details. Check the details with [Account resolver](https://api.tandapay.io/api-reference/endpoint/account-resolver.md) first.

```json M-PESA theme={null}
{
  "country": "KE",
  "currency": "KES",
  "type": "payout",
  "payload": {
    "destination": "MoMo",
    "payoutMethod": {
      "accountName": "Grace Achieng",
      "accountNumber": "254712345678",
      "code": "mpesa"
    }
  }
}
```

```json Bank account theme={null}
{
  "country": "KE",
  "currency": "KES",
  "type": "payout",
  "payload": {
    "destination": "Bank Account",
    "payoutMethod": {
      "accountName": "Kilimo Supplies Ltd",
      "accountNumber": "01100123456700",
      "code": "1243"
    }
  }
}
```

```json Paybill theme={null}
{
  "country": "KE",
  "currency": "KES",
  "type": "payout",
  "payload": {
    "destination": "Paybill",
    "payoutMethod": {
      "accountName": "Kenya Power",
      "accountNumber": "ACC-778812",
      "businessNumber": "888880"
    }
  }
}
```

```json Till theme={null}
{
  "country": "KE",
  "currency": "KES",
  "type": "payout",
  "payload": {
    "destination": "Till",
    "payoutMethod": {
      "accountName": "Mama Mboga Stores",
      "accountNumber": "123456"
    }
  }
}
```

```json Response theme={null}
{
  "success": true,
  "message": "External account created successfully.",
  "data": { "id": "ea_9Xk2LmPq" }
}
```

Store `data.id` against the recipient in your system. That's the `externalAccountId`.

> [!NOTE]
>
> You can also save a customer you charge often, with `type: "deposit"` and `firstName`, `lastName` and `phoneNumber` in `payload`. Pass the ID as `externalAccountId` on a [mobile money charge](https://api.tandapay.io/api-reference/endpoint/mobile-money-charge.md).

## Pay a beneficiary

```bash theme={null}
curl -X POST https://api.tandapay.io/api/b2b/fiat/payout \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "externalReference": "payout_5536",
    "externalAccountId": "ea_9Xk2LmPq"
  }'
```

## Manage beneficiaries

| To | Use |
| :- | :- |
| List all | [List beneficiaries](https://api.tandapay.io/api-reference/endpoint/list-beneficiaries.md) |
| Fetch one | [Get beneficiary](https://api.tandapay.io/api-reference/endpoint/get-beneficiary.md) |
| Change details | [Update beneficiary](https://api.tandapay.io/api-reference/endpoint/update-beneficiary.md) |
| Remove | [Delete beneficiary](https://api.tandapay.io/api-reference/endpoint/delete-beneficiary.md) |

When a recipient changes their bank or number, update the existing beneficiary rather than creating a new one, and delete beneficiaries you no longer pay.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.