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

# External accounts

> Store recipients as beneficiaries so repeat payouts need only an ID.

External accounts — beneficiaries — are saved records of where funds can be sent. Once stored, you
can pay a recipient by passing `externalAccountId` alone, without re-sending their name, account
number, and bank code every time.

<Tip>
  Use external accounts for anyone you pay more than once: sellers, vendors, contractors, or
  recurring disbursements. Fewer fields per request means fewer chances to send a bad account
  number.
</Tip>

## Create an external account

Send a request to
[Create an External Account](/api-reference/endpoint/create-an-external-account).

| Field      | Type   | Required | Description                                   |
| :--------- | :----- | :------: | :-------------------------------------------- |
| `country`  | String |    Yes   | ISO 3166-1 alpha-2 code                       |
| `currency` | String |    Yes   | ISO 4217 currency code                        |
| `type`     | String |    Yes   | `payout` or `deposit`                         |
| `payload`  | Object |    Yes   | Destination details — shape depends on `type` |

### Payout payload

| Field                         | Type   |   Required  | Description                                             |
| :---------------------------- | :----- | :---------: | :------------------------------------------------------ |
| `destination`                 | String |     Yes     | `MoMo`, `Bank Account`, `Paybill`, or `Till`            |
| `payoutMethod.accountName`    | String |     Yes     | Recipient name                                          |
| `payoutMethod.accountNumber`  | String |     Yes     | Account or phone number                                 |
| `payoutMethod.code`           | String | Conditional | Bank code, or mobile money operator code where required |
| `payoutMethod.branchCode`     | String | Conditional | **Required for `UG` and `TZ` bank accounts**            |
| `payoutMethod.businessNumber` | String | Conditional | M-Pesa Paybill payouts only                             |

<CodeGroup>
  ```json Mobile money theme={null}
  {
    "type": "payout",
    "country": "KE",
    "currency": "KES",
    "payload": {
      "destination": "MoMo",
      "payoutMethod": {
        "accountName": "John Doe",
        "accountNumber": "254712345678"
      }
    }
  }
  ```

  ```json Bank account theme={null}
  {
    "type": "payout",
    "country": "UG",
    "currency": "UGX",
    "payload": {
      "destination": "Bank Account",
      "payoutMethod": {
        "accountName": "Tim Drake",
        "accountNumber": "12345678",
        "code": "1910236K50",
        "branchCode": "123"
      }
    }
  }
  ```

  ```json Deposit beneficiary theme={null}
  {
    "type": "deposit",
    "country": "KE",
    "currency": "KES",
    "payload": {
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "254727272727"
    }
  }
  ```
</CodeGroup>

```json Response theme={null}
{
  "success": true,
  "message": "Successfully saved account.",
  "data": {
    "id": "8VzVZP82mQjA8AOynzal"
  }
}
```

Store the returned `id` — that is the `externalAccountId` you send when paying out.

<Warning>
  Bank accounts in **Uganda (`UG`) and Tanzania (`TZ`) require a `branchCode`**. Omitting it
  returns:

  ```json theme={null}
  {
    "success": false,
    "message": "Validation error: Branch code is required for UG and TZ.",
    "errorCode": "VALIDATION_ERROR"
  }
  ```

  Retrieve branch codes from [Get Branches](/api-reference/endpoint/get-branches).
</Warning>

## Pay out to a saved account

Reference the account by ID and omit the destination details entirely.

```json Request theme={null}
{
  "amount": 1000,
  "externalReference": "payout_recurring_001",
  "externalAccountId": "8VzVZP82mQjA8AOynzal"
}
```

<Note>
  Do **not** send `currency`, `country`, `destination`, or `payoutMethod` alongside
  `externalAccountId` — the saved details are used instead.
</Note>

## Manage saved accounts

| Operation | Endpoint                                                                   |
| :-------- | :------------------------------------------------------------------------- |
| List all  | [Get External Accounts](/api-reference/endpoint/get-external-accounts)     |
| Fetch one | [Get External Account](/api-reference/endpoint/get-external-account)       |
| Update    | [Update External Account](/api-reference/endpoint/update-external-account) |
| Delete    | [Delete External Account](/api-reference/endpoint/delete-external-account) |

## Best practices

<CardGroup cols={2}>
  <Card title="Verify before saving" icon="user-check">
    Run details through [Account Resolver](/api-reference/endpoint/account-resolver) first, so you
    are not storing an account number that will fail on every future payout.
  </Card>

  <Card title="Map IDs to your records" icon="link">
    Keep `externalAccountId` against your own recipient record so you never create duplicates.
  </Card>

  <Card title="Delete stale beneficiaries" icon="trash">
    Remove accounts for recipients you no longer pay, rather than leaving them addressable.
  </Card>

  <Card title="Update, do not duplicate" icon="pen-to-square">
    When a recipient changes bank, update the existing account so history stays on one record.
  </Card>
</CardGroup>