Beneficiaries API
Create, retrieve, and manage beneficiaries for money transfers with the Notch Pay 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
Beneficiary Object Properties
Unique identifier for the beneficiary
Beneficiary’s full name
Beneficiary’s email address
Beneficiary’s phone number (required for mobile money transfers)
Beneficiary’s account number (required for bank transfers)
Bank code for bank transfers
Two-letter ISO country code
Three-letter ISO currency code
Type of beneficiary: mobile_money, bank_account, or cash_pickup
Additional data attached to the beneficiary
Timestamp when the beneficiary was created
Timestamp when the beneficiary was last updated
API Endpoints
List All Beneficiaries
Retrieve a list of beneficiaries with pagination.
Query Parameters
Number of items per page (default: 30, max: 100)
Page number (default: 1)
Search by name, email, or phone
Filter by country code
Filter by beneficiary type
Create a Beneficiary
Create a new beneficiary.
Request Parameters
Beneficiary’s full name
Beneficiary’s email address
Beneficiary’s phone number (required for mobile money transfers)
Beneficiary’s account number (required for bank transfers)
Bank code (required for bank transfers)
Two-letter ISO country code
Three-letter ISO currency code
Type of beneficiary: mobile_money, bank_account, or cash_pickup
Additional data to attach to the beneficiary
Example Request for Mobile Money Beneficiary
Example Request for Bank Account Beneficiary
Create a new beneficiary.
Request Parameters
Beneficiary’s full name
Beneficiary’s email address
Beneficiary’s phone number (required for mobile money transfers)
Beneficiary’s account number (required for bank transfers)
Bank code (required for bank transfers)
Two-letter ISO country code
Three-letter ISO currency code
Type of beneficiary: mobile_money, bank_account, or cash_pickup
Additional data to attach to the beneficiary
Example Request for Mobile Money Beneficiary
Example Request for Bank Account Beneficiary
Update a Beneficiary
Update an existing beneficiary.
Path Parameters
ID of the beneficiary to update
Request Parameters
Beneficiary’s full name
Beneficiary’s email address
Beneficiary’s phone number
Beneficiary’s account number
Bank code
Additional data to attach to the beneficiary
Example Request
Update an existing beneficiary.
Path Parameters
ID of the beneficiary to update
Request Parameters
Beneficiary’s full name
Beneficiary’s email address
Beneficiary’s phone number
Beneficiary’s account number
Bank code
Additional data to attach to the beneficiary
Example Request
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.