The Beneficiaries API allows you to create and manage recipients for money transfers. Storing beneficiary information makes it easier to send recurring transfers to the same recipients.

​
The Beneficiary Object

{
  "id": "ben_123456789",
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+237600000000",
  "account_number": "0123456789",
  "bank_code": "SGCM",
  "country": "CM",
  "currency": "XAF",
  "type": "mobile_money",
  "metadata": {},
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:00:00Z"
}

​
Beneficiary Object Properties

​
id
string
Unique identifier for the beneficiary
​
name
string
Beneficiary’s full name
​
email
string
Beneficiary’s email address
​
phone
string
Beneficiary’s phone number (required for mobile money transfers)
​
account_number
string
Beneficiary’s account number (required for bank transfers)
​
bank_code
string
Bank code for bank transfers
​
country
string
Two-letter ISO country code
​
currency
string
Three-letter ISO currency code
​
type
string
Type of beneficiary: mobile_money, bank_account, or cash_pickup
​
metadata
object
Additional data attached to the beneficiary
​
created_at
string
Timestamp when the beneficiary was created
​
updated_at
string
Timestamp when the beneficiary was last updated

​
API Endpoints

List All Beneficiaries

GET /beneficiaries
Retrieve a list of beneficiaries with pagination.

​
Query Parameters

​
limit
integer
Number of items per page (default: 30, max: 100)
​
page
integer
Page number (default: 1)
​
search
string
Search by name, email, or phone
​
country
string
Filter by country code
​
type
string
Filter by beneficiary type

Create a Beneficiary

POST /beneficiaries
Create a new beneficiary.

​
Request Parameters

​
name
string
required
Beneficiary’s full name
​
email
string
Beneficiary’s email address
​
phone
string
Beneficiary’s phone number (required for mobile money transfers)
​
account_number
string
Beneficiary’s account number (required for bank transfers)
​
bank_code
string
Bank code (required for bank transfers)
​
country
string
required
Two-letter ISO country code
​
currency
string
required
Three-letter ISO currency code
​
type
string
required
Type of beneficiary: mobile_money, bank_account, or cash_pickup
​
metadata
object
Additional data to attach to the beneficiary

​
Example Request for Mobile Money Beneficiary

{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+237600000000",
  "country": "CM",
  "currency": "XAF",
  "type": "mobile_money",
  "metadata": {
    "relationship": "employee",
    "department": "engineering"
  }
}

​
Example Request for Bank Account Beneficiary

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "account_number": "0123456789",
  "bank_code": "SGCM",
  "country": "CM",
  "currency": "XAF",
  "type": "bank_account"
}

Retrieve a Beneficiary

GET /beneficiaries/{id}
Retrieve details of a specific beneficiary.

​
Path Parameters

​
id
string
required
ID of the beneficiary to retrieve

Update a Beneficiary

PUT /beneficiaries/{id}
Update an existing beneficiary.

​
Path Parameters

​
id
string
required
ID of the beneficiary to update

​
Request Parameters

​
name
string
Beneficiary’s full name
​
email
string
Beneficiary’s email address
​
phone
string
Beneficiary’s phone number
​
account_number
string
Beneficiary’s account number
​
bank_code
string
Bank code
​
metadata
object
Additional data to attach to the beneficiary

​
Example Request

{
  "name": "John Smith",
  "phone": "+237600000001",
  "metadata": {
    "relationship": "contractor",
    "department": "engineering"
  }
}

Delete a Beneficiary

DELETE /beneficiaries/{id}
Delete a beneficiary.

​
Path Parameters

​
id
string
required
ID of the beneficiary to delete

​
Beneficiary Types

mobile_money

For mobile money transfers to recipients’ mobile wallets.Required fields: name, phone, country, currency

bank_account

For bank transfers to recipients’ bank accounts.Required fields: name, account_number, bank_code, country, currency

cash_pickup

For transfers that can be collected as cash at pickup locations.Required fields: name, phone, country, currency

​
Best Practices

Validate Beneficiary Information

Validate phone numbers, account numbers, and bank codes before creating beneficiaries to ensure they’re in the correct format.This helps prevent transfer failures due to invalid recipient information.

Use Metadata Effectively

Use the metadata field to store additional information about your beneficiaries that’s relevant to your business.This can include employee IDs, departments, or other custom data.

Implement Beneficiary Search

Use the search parameter when listing beneficiaries to quickly find existing recipients instead of creating duplicates.Search by name, email, or phone to find matching beneficiaries.

Secure Beneficiary Data

Implement proper access controls for beneficiary management to protect sensitive financial information.Remember that all beneficiary endpoints require the X-Grant header for additional security.

Transfers API

Send money to beneficiaries

Resources API

Get information about supported banks and countries

Webhooks API

Receive notifications about beneficiary events