External accounts

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.

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.

Create an external account

Send a request to 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

{
  "type": "payout",
  "country": "KE",
  "currency": "KES",
  "payload": {
    "destination": "MoMo",
    "payoutMethod": {
      "accountName": "John Doe",
      "accountNumber": "254712345678"
    }
  }
}

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

{
  "type": "deposit",
  "country": "KE",
  "currency": "KES",
  "payload": {
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "254727272727"
  }
}

Response

{
  "success": true,
  "message": "Successfully saved account.",
  "data": {
    "id": "8VzVZP82mQjA8AOynzal"
  }
}

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

Bank accounts in Uganda (UG) and Tanzania (TZ) require a branchCode. Omitting it returns:

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

Retrieve branch codes from Get Branches.

Pay out to a saved account

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

Request

{
  "amount": 1000,
  "externalReference": "payout_recurring_001",
  "externalAccountId": "8VzVZP82mQjA8AOynzal"
}

Do not send currency, country, destination, or payoutMethod alongside externalAccountId — the saved details are used instead.

Manage saved accounts

Operation	Endpoint
List all	Get External Accounts
Fetch one	Get External Account
Update	Update External Account
Delete	Delete External Account

Best practices

Verify before saving

Run details through Account Resolver first, so you are not storing an account number that will fail on every future payout.

Map IDs to your records

Keep externalAccountId against your own recipient record so you never create duplicates.

Delete stale beneficiaries

Remove accounts for recipients you no longer pay, rather than leaving them addressable.

Update, do not duplicate

When a recipient changes bank, update the existing account so history stays on one record.

Get Started

Before You Build

Charges

Payouts

Webhooks

Testing

Errors

External accounts

Create an external account

Payout payload

Pay out to a saved account

Manage saved accounts

Best practices

Verify before saving

Map IDs to your records

Delete stale beneficiaries

Update, do not duplicate

​Create an external account

​Payout payload

​Pay out to a saved account

​Manage saved accounts

​Best practices

Verify before saving

Map IDs to your records

Delete stale beneficiaries

Update, do not duplicate

Create an external account

Payout payload

Pay out to a saved account

Manage saved accounts

Best practices