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 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.