Beneficiaries: save bank, mobile money, and wallet recipients

A beneficiary is a saved recipient you can pay again without re-entering their details. PeerPesa supports three beneficiary types: bank_account and phone_number (mobile money) for fiat payouts through offramps and withdrawals, and wallet_address for crypto sends. Create a beneficiary once, then reference its id as beneficiary_id.

Beneficiary types

Type	Use for	Required details
`bank_account`	Fiat payouts to a bank account	`bank_code`, `account_number`, `account_name`
`phone_number`	Fiat payouts to a mobile money wallet	`phone_number`, `provider`
`wallet_address`	Crypto sends to a Stellar, Celo, or Bitcoin wallet	`wallet_address`, `network`, `asset`, optional `memo`

The beneficiary object

string

Unique identifier, for example ben_3m7q2c.

string

bank_account, phone_number, or wallet_address.

string

Recipient’s full name or a label for the wallet.

string | null

ISO 3166-1 alpha-2 country code, for example KE. null for wallet_address.

string | null

Payout currency: KES, TZS, NGN, ZAR, or ZMW. null for wallet_address.

object

Recipient details for the beneficiary type.

Show properties

string

bank_account only. Recipient bank’s code.

string

bank_account only. Bank name resolved from bank_code.

string

bank_account only. Recipient’s account number.

string

bank_account only. Name on the bank account.

string

phone_number only. Phone number in international format.

string

phone_number only. Mobile money provider, for example mpesa.

string

wallet_address only. Destination wallet address.

string

wallet_address only. Network of the address: stellar, celo, or btc.

string

wallet_address only. Asset to send, for example USDC, XLM, cUSD, or USDT.

string

wallet_address only. Memo for Stellar destinations such as exchanges. Empty when not needed.

string

ISO 8601 creation timestamp.

POST /beneficiaries

Creates a beneficiary.

string

required

bank_account, phone_number, or wallet_address.

string

required

Recipient’s full name, or a label for a wallet.

string

ISO 3166-1 alpha-2 country code. Required for bank_account and phone_number.

string

Payout currency. Required for bank_account and phone_number, and must be supported for the country.

object

Required when type is bank_account.

Show properties

string

required

Recipient bank’s code.

string

required

Recipient’s account number.

string

required

Name on the bank account.

object

Required when type is phone_number.

Show properties

string

required

Phone number in international format, for example +254712345678.

string

required

Mobile money provider, for example mpesa.

object

Required when type is wallet_address.

Show properties

string

required

Destination wallet address. Validated against the network format.

string

required

stellar, celo, or btc.

string

required

Asset to send on that network. See Currencies.

string

Memo for Stellar addresses that require one, such as exchange deposit addresses.

Bank account
Phone number
Wallet address

cURL

curl -X POST https://api.peerpesa.co/v1/beneficiaries \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bank_account",
    "name": "Chinedu Okafor",
    "country": "NG",
    "fiat_currency": "NGN",
    "bank_account": {
      "bank_code": "058",
      "account_number": "0123456789",
      "account_name": "Chinedu Okafor"
    }
  }'

cURL

curl -X POST https://api.peerpesa.co/v1/beneficiaries \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone_number",
    "name": "Amina Otieno",
    "country": "KE",
    "fiat_currency": "KES",
    "phone_number": { "phone_number": "+254712345678", "provider": "mpesa" }
  }'

cURL

curl -X POST https://api.peerpesa.co/v1/beneficiaries \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "wallet_address",
    "name": "Treasury wallet",
    "wallet_address": {
      "wallet_address": "0x15cb5Ab94aEfd21A5458FEda25583C9938E83c74",
      "network": "celo",
      "asset": "USDT"
    }
  }'

{
  "id": "ben_8k2d5n",
  "type": "bank_account",
  "name": "Chinedu Okafor",
  "country": "NG",
  "fiat_currency": "NGN",
  "details": {
    "bank_code": "058",
    "bank_name": "GTBank",
    "account_number": "0123456789",
    "account_name": "Chinedu Okafor"
  },
  "created_at": "2026-10-15T05:00:00Z"
}

{
  "id": "ben_3m7q2c",
  "type": "phone_number",
  "name": "Amina Otieno",
  "country": "KE",
  "fiat_currency": "KES",
  "details": { "phone_number": "+254712345678", "provider": "mpesa" },
  "created_at": "2026-10-15T05:00:00Z"
}

{
  "id": "ben_6w4t9h",
  "type": "wallet_address",
  "name": "Treasury wallet",
  "country": null,
  "fiat_currency": null,
  "details": {
    "wallet_address": "0x15cb5Ab94aEfd21A5458FEda25583C9938E83c74",
    "network": "celo",
    "asset": "USDT",
    "memo": ""
  },
  "created_at": "2026-10-15T05:00:00Z"
}

Crypto sent to a wrong address or network cannot be reversed. Double-check wallet_address and network, and include the memo when the destination requires one.

GET /beneficiaries

Lists beneficiaries, newest first. Supports all pagination and filter parameters.

integer

default:"1"

Page number to return, starting at 1.

integer

default:"20"

Results per page, up to 100. limit is accepted as an alias.

string

Filter by beneficiary type: bank_account, phone_number, or wallet_address. Comma-separate to match several.

string

Matches name, phone number, account number, bank name, and wallet address. Minimum 2 characters.

string

Only include beneficiaries created on or after this date (YYYY-MM-DD or ISO 8601).

string

Only include beneficiaries created on or before this date (YYYY-MM-DD or ISO 8601).

string

Filter by ISO country code, for example KE.

string

Filter by payout currency, for example KES.

string

Filter wallet_address beneficiaries by network: stellar, celo, or btc.

string

default:"created_at"

created_at or name.

string

default:"desc"

desc or asc.

curl "https://api.peerpesa.co/v1/beneficiaries?page=1&size=20&type=phone_number&country=KE" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const res = await fetch(
  "https://api.peerpesa.co/v1/beneficiaries?page=1&size=20&type=phone_number&country=KE",
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
const { data, pagination } = await res.json();

Response

{
  "data": [
    {
      "id": "ben_3m7q2c",
      "type": "phone_number",
      "name": "Amina Otieno",
      "country": "KE",
      "fiat_currency": "KES",
      "details": { "phone_number": "+254712345678", "provider": "mpesa" },
      "created_at": "2026-10-15T05:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 1,
    "total_pages": 1
  }
}

GET /beneficiaries/{id}

Retrieves one beneficiary. Returns 404 with code not_found if the ID does not exist.

cURL

curl https://api.peerpesa.co/v1/beneficiaries/ben_3m7q2c \
  -H "Authorization: Bearer $ACCESS_TOKEN"

DELETE /beneficiaries/{id}

Deletes a beneficiary. Returns 204 No Content on success. Past transactions to this beneficiary are not affected.

cURL

curl -X DELETE https://api.peerpesa.co/v1/beneficiaries/ben_3m7q2c \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Errors

Code	Status	Cause
`missing_parameter`	400	The details object for the `type` is missing, for example `bank_account` when `type` is `bank_account`.
`invalid_parameter`	400	Unknown `type` or an invalid account number. `param` names the field.
`invalid_phone_number`	422	Phone number format is invalid for the country.
`invalid_wallet_address`	422	`wallet_address` is not valid for the `network`.
`unsupported_pair`	422	`fiat_currency` or `provider` is not supported for the `country`.
`unsupported_asset`	422	`asset` is not available on the chosen `network`.
`not_found`	404	No beneficiary with this ID.

​Beneficiary types

​The beneficiary object

​POST /beneficiaries

​GET /beneficiaries

​GET /beneficiaries/{id}

​DELETE /beneficiaries/{id}

​Errors

Beneficiary types

The beneficiary object

POST /beneficiaries

GET /beneficiaries

GET /beneficiaries/{id}

DELETE /beneficiaries/{id}

Errors