Create a Beneficiary (Legacy)

Overview

This service is used to create a beneficiary through the API. Beneficiaries undergo an approval process once registered. Depending on the business type, beneficiaries may go through automated or manual compliance review before outgoing payments can be dispatched.

Resource Access

• HTTP Method: POST
• Endpoint: /profile/v2.1/beneficiaries
• Authentication: Bearer token required

Request Headers

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

Request Body

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

Request Fields

Field	Type	Required	Description
beneficiaryEntityType	string	Yes	individual or company.
beneficiaryFirstName	string	Conditional	First name of individual beneficiary.
beneficiaryLastName	string	Conditional	Last name of individual beneficiary.
beneficiaryCompanyName	string	Conditional	Company name (required if entity type is company).
currency	string	Yes	3-letter ISO 4217 currency code.
beneficiaryCountryCode	string	Yes	2-letter ISO 3166-1 alpha-2 country code.
accountNumber	string	Yes	Bank account number or mobile money phone number.
nationalId	string	Yes	Bank routing / SWIFT / IFSC / sort code.
country	string	Yes	Full name of the country.
clientReference	string	No	Custom tracking reference.
isMobileMoney	boolean	No	Set to true if this is a mobile money wallet recipient.
beneficiaryEmail	string	No	Email address of the beneficiary.

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",
    "beneficiaryCompanyName": null,
    "beneficiaryCountryCode": "IN",
    "beneficiaryEntityType": "individual",
    "beneficiaryPostcode": "110066",
    "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	Flag indicating whether beneficiary was created successfully.
account.id	number	Unique ID of the registered beneficiary.
account.accountNumber	string	Bank or mobile money account number.
account.bankName	string	Resolved bank name.
account.reference	string	Unique beneficiary reference (e.g. RP-17062022-001).
account.status	string	Approval status (approved, pending, rejected).
account.currency	string	Currency of the beneficiary account.

Error Responses

• 400 Bad Request: Invalid parameters or malformed request
• 401 Unauthorized: Missing or invalid Bearer authentication token
• 403 Forbidden: Insufficient account permissions
• 404 Not Found: Resource not found
• 500 Internal Server Error: An internal server error occurred

Code Examples

Base URL

Production: https://api.ahrvo.network
Staging:    https://gateway.ahrvo.network

cURL

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

Python

import requests

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

response = requests.post(url, json=payload, headers=headers)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/ibans/v2/profile/v2.1/beneficiaries';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};
const data = {
  beneficiaryEntityType: 'individual',
  beneficiaryFirstName: 'Jon',
  beneficiaryLastName: 'Doe',
  currency: 'INR',
  beneficiaryCountryCode: 'IN',
  accountNumber: '2000293918130',
  nationalId: 'PUNB0644100',
  country: 'India',
  isMobileMoney: false
};

axios.post(url, data, { headers })
  .then(response => console.log(response.data))
  .catch(error => console.error(error.response ? error.response.data : error.message));

Usage Notes

• For mobile money recipients, set isMobileMoney: true and pass provider name in nationalId (e.g. M-PESA).
• Keep the returned account.id for use in payment requests.

Interactive API Explorer