Create Beneficiary (Atlas)

Overview

The POST /banking/ibans/v2/recipients endpoint registers a new payout recipient in the Atlas system. The endpoint supports three primary categories of beneficiaries via schema oneOf validation:

Stablecoin Beneficiary (STABLECOIN): Requires cryptoCurrency (USDC or USDT), blockchain (ethereum_erc20), cryptoCurrencyWalletAddress (valid 0x-prefixed 40-character hex address), and cryptoCurrencyWalletHostedOption.
- If accountLabel (wallet nickname) is provided, companyName is required.
- If accountLabel is omitted, either companyName or both firstName + lastName must be provided, along with full beneficiaryAddress.
Bank Beneficiary (Domestic / Non-International): LOCAL, MOBILE_MONEY, HK_BANK. Requires accountNumber, bankCode, bankName, and bankAddress.countryCode.
- company: requires companyName.
- individual: requires firstName and lastName.
- myOrganisation: no name fields required.
Bank Beneficiary (International SWIFT): INTERNATIONAL. In addition to bank details, requires beneficiaryAddress.addressLine1 and beneficiaryAddress.countryCode.

SWIFT codes belonging to sanctioned (OORA - Out of Risk Appetite) countries are automatically rejected. Furthermore, when the client company is classified as financial services or crypto, the nestedType attribute is mandatory.

Resource Access

HTTP Method: POST
Endpoint: /banking/ibans/v2/recipients
Authentication: Bearer token required

Request Headers

Header	Value	Required	Description
`Authorization`	`Bearer {access_token}`	Yes	JWT Bearer access token
`Content-Type`	`application/json`	Yes	Request payload format
`Accept`	`application/json`	Yes	Response payload format
`x-api-key`	string	No	Optional API key

Request Body

Core Requirements Matrix

Payment Mode	Beneficiary Type	Mandatory Fields
`LOCAL` / `MOBILE_MONEY` / `HK_BANK`	`company`	`currencyId`, `paymentMode`, `beneficiaryType`, `accountNumber`, `bankCode`, `bankName`, `bankAddress.countryCode`, `companyName`
`LOCAL` / `MOBILE_MONEY` / `HK_BANK`	`individual`	`currencyId`, `paymentMode`, `beneficiaryType`, `accountNumber`, `bankCode`, `bankName`, `bankAddress.countryCode`, `firstName`, `lastName`
`LOCAL` / `MOBILE_MONEY` / `HK_BANK`	`myOrganisation`	`currencyId`, `paymentMode`, `beneficiaryType`, `accountNumber`, `bankCode`, `bankName`, `bankAddress.countryCode`
`INTERNATIONAL`	`company`	All local fields + `companyName` + `beneficiaryAddress.addressLine1` + `beneficiaryAddress.countryCode`
`INTERNATIONAL`	`individual`	All local fields + `firstName` + `lastName` + `beneficiaryAddress.addressLine1` + `beneficiaryAddress.countryCode`
`STABLECOIN`	Any	`currencyId`, `paymentMode` (`STABLECOIN`), `beneficiaryType`, `cryptoCurrency`, `blockchain`, `cryptoCurrencyWalletAddress`, `cryptoCurrencyWalletHostedOption`

Key Request Fields

Field	Type	Required	Description
`currencyId`	integer	Yes	Supported currency identifier (e.g., `1` for GBP, `2` for EUR, `4` for USD).
`paymentMode`	string	Yes	Payment route: `LOCAL`, `INTERNATIONAL`, `MOBILE_MONEY`, `STABLECOIN`, `HK_BANK`.
`beneficiaryType`	string	Yes	Type of entity: `company`, `individual`, `myOrganisation`.
`accountNumber`	string	Conditional	Account number or IBAN. Required for non-stablecoin payment modes.
`accountLabel`	string	No	Wallet nickname (max 50 chars) for stablecoin beneficiaries.
`bankCode`	string	Conditional	Sort code, routing number, BIC, or clearing code. Required for bank modes.
`bankName`	string	Conditional	Official name of receiving financial institution.
`companyName`	string	Conditional	Required when `beneficiaryType` is `company`.
`firstName`	string	Conditional	Required when `beneficiaryType` is `individual`.
`lastName`	string	Conditional	Required when `beneficiaryType` is `individual`.
`bankAddress`	object	Conditional	Bank location object with required `countryCode` (2-letter ISO code).
`beneficiaryAddress`	object	Conditional	Recipient address object (`addressLine1`, `city`, `countryCode`, `postCode`, `stateOrProvience`).
`cryptoCurrency`	string	Conditional	`USDC` or `USDT`. Required for `STABLECOIN`.
`blockchain`	string	Conditional	`ethereum_erc20`. Required for `STABLECOIN`.
`cryptoCurrencyWalletAddress`	string	Conditional	0x-prefixed 40-character hex address. Required for `STABLECOIN`.
`cryptoCurrencyWalletHostedOption`	string	Conditional	`dedicated_wallet_via_custodian`, `exchange`, `self_hosted_wallet`, or `not_known`.
`cryptoCurrencyWalletHostedOn`	string	No	Specific custodian/exchange identifier (e.g. `exchange_coinbase`, `custodian_bit_go`, `self_hosted_metamask`).
`nestedType`	string	Conditional	Required for financial services/crypto clients: `OPEX`, `NESTED_CUSTOMER`, `NESTED_PAYEE`.

Request Examples

1. Corporate Bank Beneficiary (Domestic Local)

{
  "currencyId": 1,
  "paymentMode": "LOCAL",
  "beneficiaryType": "company",
  "companyName": "Acme Global Logistics Ltd",
  "accountNumber": "20406080",
  "bankCode": "200000",
  "bankName": "Barclays Bank UK",
  "bankAddress": {
    "countryCode": "GB",
    "city": "London",
    "address": "1 Churchill Place"
  },
  "partyType": "Third_Party"
}

2. Stablecoin Beneficiary (USDC ERC-20)

{
  "currencyId": 4,
  "paymentMode": "STABLECOIN",
  "beneficiaryType": "company",
  "companyName": "Alpha Trading Corp",
  "accountLabel": "Alpha Treasury USDC",
  "cryptoCurrency": "USDC",
  "blockchain": "ethereum_erc20",
  "cryptoCurrencyWalletAddress": "0x71C84712F2843A1B51390467aC01C5B72803b9b3",
  "cryptoCurrencyWalletHostedOption": "exchange",
  "cryptoCurrencyWalletHostedOn": "exchange_coinbase",
  "partyType": "Third_Party"
}

3. International Wire Beneficiary (SWIFT)

{
  "currencyId": 4,
  "paymentMode": "INTERNATIONAL",
  "beneficiaryType": "company",
  "companyName": "Nairobi Import Export Co",
  "accountNumber": "010029384756",
  "bankCode": "BARCKENX",
  "bankName": "Absa Bank Kenya PLC",
  "bankAddress": {
    "countryCode": "KE",
    "city": "Nairobi",
    "address": "Absa Headquarters, Waiyaki Way"
  },
  "beneficiaryAddress": {
    "countryCode": "KE",
    "city": "Nairobi",
    "addressLine1": "Plot 45 Enterprise Road Industrial Area",
    "postCode": "00100"
  },
  "partyType": "Third_Party"
}

Response

Success Response (200 OK)

{
  "success": true,
  "accounts": {
    "id": 948201,
    "companyId": 1045,
    "currencyId": 1,
    "paymentMode": "LOCAL",
    "beneficiaryType": "company",
    "companyName": "Acme Global Logistics Ltd",
    "accountNumber": "20406080",
    "bankCode": "200000",
    "bankName": "Barclays Bank UK",
    "bankAddress": {
      "countryCode": "GB",
      "city": "London",
      "address": "1 Churchill Place"
    },
    "verificationState": "approved",
    "isAccountActive": true,
    "isArchived": false,
    "createdAt": "2026-09-15T18:30:00.000Z"
  }
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the beneficiary was registered successfully.
`accounts.id`	integer	Unique identifier for the created beneficiary.
`accounts.companyId`	integer	Company profile associated with this recipient.
`accounts.verificationState`	string	Screening status: `approved`, `pending`, or `rejected`.
`accounts.isAccountActive`	boolean	Whether this account is active and available for payout routing.
`accounts.createdAt`	string (ISO-8601)	Timestamp when the beneficiary was created.

Error Responses

400 Bad Request: Invalid body parameters, missing mandatory conditional fields, or failed pattern validation.
401 Unauthorized: Missing or expired Bearer token.
404 Not Found: Currency or risk factor entry not found.
500 Internal Server Error: Internal platform error.

Code Examples

cURL

curl -X POST "https://gateway.ahrvo.network/banking/ibans/v2/recipients" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "currencyId": 1,
    "paymentMode": "LOCAL",
    "beneficiaryType": "company",
    "companyName": "Acme Global Logistics Ltd",
    "accountNumber": "20406080",
    "bankCode": "200000",
    "bankName": "Barclays Bank UK",
    "bankAddress": {
      "countryCode": "GB"
    }
  }'

Python

import requests

url = "https://gateway.ahrvo.network/banking/ibans/v2/recipients"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

payload = {
    "currencyId": 1,
    "paymentMode": "LOCAL",
    "beneficiaryType": "company",
    "companyName": "Acme Global Logistics Ltd",
    "accountNumber": "20406080",
    "bankCode": "200000",
    "bankName": "Barclays Bank UK",
    "bankAddress": {
        "countryCode": "GB"
    }
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print("Beneficiary ID:", data["accounts"]["id"])

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/ibans/v2/recipients';
const headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

const payload = {
  currencyId: 1,
  paymentMode: 'LOCAL',
  beneficiaryType: 'company',
  companyName: 'Acme Global Logistics Ltd',
  accountNumber: '20406080',
  bankCode: '200000',
  bankName: 'Barclays Bank UK',
  bankAddress: {
    countryCode: 'GB'
  }
};

axios.post(url, payload, { headers })
  .then(res => console.log('Beneficiary Created:', res.data.accounts.id))
  .catch(err => console.error(err.response ? err.response.data : err.message));

Overview​

Resource Access​

Request Headers​

Request Body​

Core Requirements Matrix​

Key Request Fields​

Request Examples​

1. Corporate Bank Beneficiary (Domestic Local)​

2. Stablecoin Beneficiary (USDC ERC-20)​

3. International Wire Beneficiary (SWIFT)​

Response​

Success Response (200 OK)​

Response Fields​

Error Responses​

Code Examples​

cURL​

Python​

JavaScript (Node.js)​

Interactive API Explorer​