Beneficiaries API

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

string

Unique identifier for the beneficiary

string

Beneficiary’s full name

string

Beneficiary’s email address

string

Beneficiary’s phone number (required for mobile money transfers)

string

Beneficiary’s account number (required for bank transfers)

string

Bank code for bank transfers

string

Two-letter ISO country code

string

Three-letter ISO currency code

string

Type of beneficiary: mobile_money, bank_account, or cash_pickup

object

Additional data attached to the beneficiary

string

Timestamp when the beneficiary was created

string

Timestamp when the beneficiary was last updated

API Endpoints

List All Beneficiaries

Request
Response

GET /beneficiaries

Retrieve a list of beneficiaries with pagination.

Query Parameters

integer

Number of items per page (default: 30, max: 100)

integer

Page number (default: 1)

string

Search by name, email, or phone

string

Filter by country code

string

Filter by beneficiary type

{
  "code": 200,
  "status": "OK",
  "message": "Beneficiaries retrieved",
  "totals": 50,
  "last_page": 2,
  "current_page": 1,
  "selected": 30,
  "items": [
    {
      "id": "ben_123456789",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+237600000000",
      "country": "CM",
      "currency": "XAF",
      "type": "mobile_money",
      "created_at": "2023-01-01T12:00:00Z"
    },
    // More beneficiaries...
  ]
}

Create a Beneficiary

Request
Response

POST /beneficiaries

Create a new beneficiary.

Request Parameters

string

required

Beneficiary’s full name

string

Beneficiary’s email address

string

Beneficiary’s phone number (required for mobile money transfers)

string

Beneficiary’s account number (required for bank transfers)

string

Bank code (required for bank transfers)

string

required

Two-letter ISO country code

string

required

Three-letter ISO currency code

string

required

Type of beneficiary: mobile_money, bank_account, or cash_pickup

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"
  }
}

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

fetch('https://api.notchpay.co/beneficiaries', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'X-Grant': 'YOUR_PRIVATE_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(beneficiary)
});

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"
}

{
  "status": "Created",
  "message": "Beneficiary created",
  "code": 201,
  "beneficiary": {
    "id": "ben_123456789",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+237600000000",
    "country": "CM",
    "currency": "XAF",
    "type": "mobile_money",
    "metadata": {
      "relationship": "employee",
      "department": "engineering"
    },
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z"
  }
}

The required fields depend on the beneficiary type. For mobile money transfers, a phone number is required. For bank transfers, account number and bank code are required.

Retrieve a Beneficiary

Request
Response

GET /beneficiaries/{id}

Retrieve details of a specific beneficiary.

Path Parameters

string

required

ID of the beneficiary to retrieve

{
  "status": "OK",
  "message": "Beneficiary retrieved",
  "code": 200,
  "beneficiary": {
    "id": "ben_123456789",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+237600000000",
    "country": "CM",
    "currency": "XAF",
    "type": "mobile_money",
    "metadata": {
      "relationship": "employee",
      "department": "engineering"
    },
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z"
  }
}

Update a Beneficiary

Request
Response

PUT /beneficiaries/{id}

Update an existing beneficiary.

Path Parameters

string

required

ID of the beneficiary to update

Request Parameters

string

Beneficiary’s full name

string

Beneficiary’s email address

string

Beneficiary’s phone number

string

Beneficiary’s account number

string

Bank code

object

Additional data to attach to the beneficiary

Example Request

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

{
  "status": "OK",
  "message": "Beneficiary updated",
  "code": 200,
  "beneficiary": {
    "id": "ben_123456789",
    "name": "John Smith",
    "email": "john@example.com",
    "phone": "+237600000001",
    "country": "CM",
    "currency": "XAF",
    "type": "mobile_money",
    "metadata": {
      "relationship": "contractor",
      "department": "engineering"
    },
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-02T10:00:00Z"
  }
}

You cannot change the country, currency, or type of an existing beneficiary. If you need to change these fields, create a new beneficiary instead.

Delete a Beneficiary

Request
Response

DELETE /beneficiaries/{id}

Delete a beneficiary.

Path Parameters

string

required

ID of the beneficiary to delete

{
  "status": "OK",
  "message": "Beneficiary deleted",
  "code": 200
}

Deleting a beneficiary will not delete any associated transfers. It only removes the beneficiary record itself.

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

Introduction

Core Resources

Additional Resources

API Specification

The Beneficiary Object

Beneficiary Object Properties

API Endpoints

List All Beneficiaries

Query Parameters

Create a Beneficiary

Request Parameters

Example Request for Mobile Money Beneficiary

Example Request for Bank Account Beneficiary

Retrieve a Beneficiary

Path Parameters

Update a Beneficiary

Path Parameters

Request Parameters

Example Request

Delete a Beneficiary

Path Parameters

Beneficiary Types

mobile_money

bank_account

cash_pickup

Best Practices

Validate Beneficiary Information

Use Metadata Effectively

Implement Beneficiary Search

Secure Beneficiary Data

Transfers API

Resources API

Webhooks API

​The Beneficiary Object

​Beneficiary Object Properties

​API Endpoints

List All Beneficiaries

​Query Parameters

Create a Beneficiary

​Request Parameters

​Example Request for Mobile Money Beneficiary

​Example Request for Bank Account Beneficiary

Retrieve a Beneficiary

​Path Parameters

Update a Beneficiary

​Path Parameters

​Request Parameters

​Example Request

Delete a Beneficiary

​Path Parameters

​Beneficiary Types

mobile_money

bank_account

cash_pickup

​Best Practices

Validate Beneficiary Information

Use Metadata Effectively

Implement Beneficiary Search

Secure Beneficiary Data

​Related Resources

Transfers API

Resources API

Webhooks API

The Beneficiary Object

Beneficiary Object Properties

API Endpoints

Query Parameters

Request Parameters

Example Request for Mobile Money Beneficiary

Example Request for Bank Account Beneficiary

Path Parameters

Path Parameters

Request Parameters

Example Request

Path Parameters

Beneficiary Types

Best Practices

Related Resources