Create a Beneficiary

Overview

This service is used to create a beneficiary through the API. Beneficiaries undergo an approval process once they are created. This is subject to the type of business; if you are a Money Services Business (MSB), beneficiaries will go through an approval process in the live environment.

Supports individual bank accounts, corporate entities, and mobile money wallets across international banking schemes. Once registered, the beneficiary receives a unique id for subsequent payout execution.

Resource Access

HTTP Method: POST
Endpoint: /profile/v2.1/beneficiaries
Authentication: Bearer token required (Authorization: Bearer {access_token})

Request Headers

Header	Value	Required	Description
`Accept`	`application/json`	Yes	Content type for response
`Authorization`	`Bearer {access_token}`	Yes	Bearer token for authentication
`Content-Type`	`application/json`	Yes	Request body content type
`x-api-key`	string	No	Optional API key

Request Body

Individual Beneficiary Example

{
  "beneficiaryEntityType": "individual",
  "beneficiaryFirstName": "Jon",
  "beneficiaryLastName": "Doe",
  "currency": "INR",
  "beneficiaryCountryCode": "IN",
  "accountNumber": "2000293918130",
  "nationalId": "PUNB0644100",
  "country": "India",
  "clientReference": "Test Beneficiary For Individual",
  "isMobileMoney": false
}

Corporate Beneficiary Example

{
  "beneficiaryEntityType": "company",
  "beneficiaryCompanyName": "OLSEN INDUSTRIA E COMERCIO SA",
  "currency": "INR",
  "beneficiaryCountryCode": "IN",
  "accountNumber": "2000293918130",
  "nationalId": "PUNB0644100",
  "country": "India",
  "clientReference": "Test Beneficiary For Company",
  "isMobileMoney": false
}

Mobile Money Beneficiary Example

{
  "beneficiaryEntityType": "individual",
  "currency": "KES",
  "beneficiaryCountryCode": "KE",
  "accountNumber": "+254-900888380",
  "nationalId": "M-PESA",
  "country": "Kenya",
  "beneficiaryFirstName": "Jane",
  "beneficiaryLastName": "Doe",
  "beneficiaryEmail": "jane.doe@example.com",
  "clientReference": "Test Mobile Money Beneficiary",
  "isMobileMoney": true
}

Request Fields

Field	Type	Required	Description
`beneficiaryEntityType`	string	Yes	Either `individual` or `company`.
`currency`	string	Yes	3-letter ISO 4217 currency code (e.g. `INR`, `USD`, `KES`).
`beneficiaryCountryCode`	string	Yes	2-letter ISO country code (e.g. `IN`, `US`, `KE`).
`accountNumber`	string	Yes	Account number, IBAN, or mobile money phone number.
`country`	string	Yes	Full country name.
`nationalId`	string	No	Bank IFSC code, routing code, or national identifier.
`beneficiaryFirstName`	string	Required if individual	First name of the individual recipient.
`beneficiaryLastName`	string	Required if individual	Last name of the individual recipient.
`beneficiaryCompanyName`	string	Required if company	Registered business name.
`beneficiaryEmail`	string	No	Email address of the recipient.
`clientReference`	string	No	Client internal reference identifier.
`isMobileMoney`	boolean	No	Set to `true` for mobile money wallets (e.g. M-Pesa).

Response

Success Response (200 OK)

{
  "success": true,
  "account": {
    "id": 3994,
    "accountNumber": "2000293918130",
    "bankName": "Punjab National Bank",
    "beneficiaryAddress": "7, Bhikaji Cama Place Africa Avenue",
    "beneficiaryCity": "New Delhi",
    "beneficiaryCountryCode": "IN",
    "beneficiaryEntityType": "individual",
    "country": "India",
    "reference": "RP-17062022-001",
    "beneficiaryFirstName": "Jon",
    "beneficiaryLastName": "Doe",
    "nationalId": "PUNB0644100",
    "currency": "INR",
    "clientReference": "Test Beneficiary For Individual",
    "status": "approved"
  }
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates whether the beneficiary creation succeeded (`true` or `false`).
`account.id`	number	Unique system-assigned identifier for the beneficiary.
`account.accountNumber`	string	Stored account number or IBAN.
`account.bankName`	string	Financial institution name resolved by the banking network.
`account.beneficiaryEntityType`	string	Recipient entity type (`individual` or `company`).
`account.currency`	string	Payout currency code.
`account.reference`	string	System reference number.
`account.status`	string	Approval status (e.g. `approved`, `pending verification`).

Error Responses

400 Bad Request: Validation failure or missing required fields.
401 Unauthorized: Missing or expired access token.
403 Forbidden: Insufficient account permissions.
500 Internal Server Error: Internal system failure.

Code Examples

cURL

curl -X POST "https://api.ahrvo.network/banking/ibans/v2/profile/v2.1/beneficiaries" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "beneficiaryEntityType": "individual",
    "beneficiaryFirstName": "Jon",
    "beneficiaryLastName": "Doe",
    "currency": "INR",
    "beneficiaryCountryCode": "IN",
    "accountNumber": "2000293918130",
    "nationalId": "PUNB0644100",
    "country": "India",
    "clientReference": "Test Beneficiary For Individual",
    "isMobileMoney": false
  }'

Python

import requests

url = "https://api.ahrvo.network/banking/ibans/v2/profile/v2.1/beneficiaries"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "beneficiaryEntityType": "individual",
    "beneficiaryFirstName": "Jon",
    "beneficiaryLastName": "Doe",
    "currency": "INR",
    "beneficiaryCountryCode": "IN",
    "accountNumber": "2000293918130",
    "nationalId": "PUNB0644100",
    "country": "India",
    "clientReference": "Test Beneficiary For Individual",
    "isMobileMoney": False
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print("Beneficiary ID:", data.get("account", {}).get("id"))

JavaScript / Node.js

const response = await fetch("https://api.ahrvo.network/banking/ibans/v2/profile/v2.1/beneficiaries", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    beneficiaryEntityType: "individual",
    beneficiaryFirstName: "Jon",
    beneficiaryLastName: "Doe",
    currency: "INR",
    beneficiaryCountryCode: "IN",
    accountNumber: "2000293918130",
    nationalId: "PUNB0644100",
    country: "India",
    clientReference: "Test Beneficiary For Individual",
    isMobileMoney: false
  })
});

const result = await response.json();
console.log("Created Beneficiary:", result.account?.id);

Overview​

Resource Access​

Request Headers​

Request Body​

Individual Beneficiary Example​

Corporate Beneficiary Example​

Mobile Money Beneficiary Example​

Request Fields​

Response​

Success Response (200 OK)​

Response Fields​

Error Responses​

Code Examples​

cURL​

Python​

JavaScript / Node.js​

Interactive API Explorer​