Create Recipient

Overview

The Create Recipient API allows you to add a new payment recipient with their banking details. Recipients must be verified and have an 'AVAILABLE' status before sending external payments. Required verification and banking details vary by region and payment channel.

Resource Access

HTTP Method: POST
Endpoint: /banking/iban/api/recipient/v2/create
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
`on-behalf-of`	string	No	Customer ID for on-behalf-of operations

Request Body

The request body should contain a JSON object with the following structure:

{
  "holder_type": "PERSONAL",
  "account_type": "RECIPIENT_BANK",
  "bank_detail": {
    "currency": "INR",
    "account_name": "SHASHANK VIJAYSHANKAR TIWARI",
    "account_no": "703912345678",
    "bank_name": "BANK OF BARODA",
    "bank_code": "006",
    "account_type": "CHECKING",
    "location": "IN",
    "contact_phone": "007 3700 7457",
    "branch_name": "THANE BRANCH",
    "branch_code": "391",
    "ifsc_code": "HDFC0000001",
    "sort_code": "87",
    "address": "SUMAN HEIGHTS LODHA HERITAGE NAVNEET NAGAR MAHARASHTRA THANE INDIA",
    "province": "MAHARASHTRA",
    "city": "THANE",
    "swift_code": "CITIINHFXXX",
    "routing_no": "0006391",
    "iban": "HU58711204120061837086422231",
    "cert_type": "02",
    "cert_no": "CS8899966"
  },
  "recipient_detail": {
    "recipient_type": "20",
    "recipient_location": "IN",
    "phone_prefix": "+91",
    "phone_no": "9876543210",
    "email": "recipient@example.com",
    "address": "SUMAN HEIGHTS LODHA HERITAGE NAVNEET NAGAR MAHARASHTRA THANE INDIA",
    "address_state": "MAHARASHTRA",
    "address_city": "THANE",
    "address_street": "NAVNEET NAGAR",
    "address_postcode": "5110",
    "name": "SHASHANK VIJAYSHANKAR TIWARI",
    "partner_user_id": "P298UI839KADY381"
  },
  "document": "8f7d6e5c-4b3a-2f1d-9e8c-7b6a5d4c3f2e"
}

Request Fields

Top Level Fields

Field	Type	Required	Description
`holder_type`	string	Yes	Type of account holder: `PERSONAL` or `BUSINESS`
`account_type`	string	Yes	Type of account: `RECIPIENT_BANK`
`bank_detail`	object	Yes	Banking information object
`recipient_detail`	object	Yes	Recipient personal information object
`document`	string (UUID)	No	Document ID from file upload

Bank Detail Fields

Field	Type	Required	Description
`currency`	string	Yes	Currency code (e.g., INR, USD, EUR)
`account_name`	string	Yes	Name on the bank account
`account_no`	string	Yes	Bank account number
`bank_name`	string	Yes	Name of the bank
`bank_code`	string	No	Bank code
`account_type`	string	Yes	Account type: `CHECKING` or `SAVINGS`
`location`	string	Yes	Country code (ISO 2-letter)
`contact_phone`	string	No	Contact phone number
`branch_name`	string	No	Bank branch name
`branch_code`	string	No	Bank branch code
`ifsc_code`	string	No	IFSC code (India)
`sort_code`	string	No	Sort code (UK)
`address`	string	No	Bank address
`province`	string	No	Province/state
`city`	string	No	City
`swift_code`	string	No	SWIFT/BIC code
`routing_no`	string	No	Routing number (US)
`iban`	string	No	IBAN (Europe)
`cert_type`	string	No	Certificate type
`cert_no`	string	No	Certificate number

Recipient Detail Fields

Field	Type	Required	Description
`recipient_type`	string	Yes	Type code of recipient
`recipient_location`	string	Yes	Country code (ISO 2-letter)
`phone_prefix`	string	Yes	Country code prefix
`phone_no`	string	Yes	Phone number
`email`	string	Yes	Email address
`address`	string	Yes	Full address
`address_state`	string	No	State/province
`address_city`	string	Yes	City
`address_street`	string	No	Street address
`address_postcode`	string	Yes	Postal/ZIP code
`name`	string	Yes	Recipient full name
`partner_user_id`	string	Yes	Your unique identifier for this recipient

Response

Success Response (201 Created)

{
  "recipient_id": "RCPT_12345678",
  "holder_type": "PERSONAL",
  "account_type": "RECIPIENT_BANK",
  "status": "PENDING",
  "bank_detail": {
    "currency": "INR",
    "account_name": "SHASHANK VIJAYSHANKAR TIWARI",
    "account_no": "****5678",
    "bank_name": "BANK OF BARODA",
    "location": "IN"
  },
  "recipient_detail": {
    "name": "SHASHANK VIJAYSHANKAR TIWARI",
    "email": "recipient@example.com",
    "phone_prefix": "+91",
    "phone_no": "9876543210"
  },
  "created_at": "2026-01-13T10:00:00.000Z"
}

Response Fields

Field	Type	Description
`recipient_id`	string	Unique identifier for the recipient
`holder_type`	string	Type of account holder
`account_type`	string	Type of account
`status`	string	Recipient status
`bank_detail`	object	Masked banking information
`recipient_detail`	object	Recipient information
`created_at`	string (date-time)	Creation timestamp

Recipient Status Values

PENDING: Recipient created and under review
AVAILABLE: Recipient verified and ready for payments
DECLINED: Recipient verification failed
SUSPENDED: Recipient temporarily suspended

Error Responses

400 Bad Request: Invalid input data (missing required fields, invalid format)
401 Unauthorized: Invalid or missing authentication token
404 Not Found: Customer not found (when using on-behalf-of)
409 Conflict: Recipient already exists
422 Unprocessable Entity: Validation errors in banking details

Code Examples

cURL

curl -X POST \
  'https://gateway.ahrvo.network/banking/iban/api/recipient/v2/create' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "holder_type": "PERSONAL",
    "account_type": "RECIPIENT_BANK",
    "bank_detail": {
      "currency": "INR",
      "account_name": "SHASHANK VIJAYSHANKAR TIWARI",
      "account_no": "703912345678",
      "bank_name": "BANK OF BARODA",
      "account_type": "CHECKING",
      "location": "IN"
    },
    "recipient_detail": {
      "recipient_type": "20",
      "recipient_location": "IN",
      "phone_prefix": "+91",
      "phone_no": "9876543210",
      "email": "recipient@example.com",
      "address": "THANE MAHARASHTRA INDIA",
      "address_city": "THANE",
      "address_postcode": "5110",
      "name": "SHASHANK VIJAYSHANKAR TIWARI",
      "partner_user_id": "P298UI839KADY381"
    }
  }'

Python

import requests

url = "https://gateway.ahrvo.network/banking/iban/api/recipient/v2/create"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "holder_type": "PERSONAL",
    "account_type": "RECIPIENT_BANK",
    "bank_detail": {
        "currency": "INR",
        "account_name": "SHASHANK VIJAYSHANKAR TIWARI",
        "account_no": "703912345678",
        "bank_name": "BANK OF BARODA",
        "account_type": "CHECKING",
        "location": "IN"
    },
    "recipient_detail": {
        "recipient_type": "20",
        "recipient_location": "IN",
        "phone_prefix": "+91",
        "phone_no": "9876543210",
        "email": "recipient@example.com",
        "address": "THANE MAHARASHTRA INDIA",
        "address_city": "THANE",
        "address_postcode": "5110",
        "name": "SHASHANK VIJAYSHANKAR TIWARI",
        "partner_user_id": "P298UI839KADY381"
    }
}

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

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/iban/api/recipient/v2/create';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};
const data = {
  holder_type: 'PERSONAL',
  account_type: 'RECIPIENT_BANK',
  bank_detail: {
    currency: 'INR',
    account_name: 'SHASHANK VIJAYSHANKAR TIWARI',
    account_no: '703912345678',
    bank_name: 'BANK OF BARODA',
    account_type: 'CHECKING',
    location: 'IN'
  },
  recipient_detail: {
    recipient_type: '20',
    recipient_location: 'IN',
    phone_prefix: '+91',
    phone_no: '9876543210',
    email: 'recipient@example.com',
    address: 'THANE MAHARASHTRA INDIA',
    address_city: 'THANE',
    address_postcode: '5110',
    name: 'SHASHANK VIJAYSHANKAR TIWARI',
    partner_user_id: 'P298UI839KADY381'
  }
};

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

Usage Notes

Recipients start with PENDING status during verification
Account numbers are masked in responses for security
Required fields vary by country and payment method
Monitor recipient status via webhooks
IBAN is required for European recipients
SWIFT code is required for international wire transfers
IFSC code is required for Indian recipients
Routing number is required for US recipients
Upload verification documents before creating recipients when required

Overview​

Resource Access​

Request Headers​

Request Body​

Request Fields​

Top Level Fields​

Bank Detail Fields​

Recipient Detail Fields​

Response​

Success Response (201 Created)​

Response Fields​

Recipient Status Values​

Error Responses​

Code Examples​

cURL​

Python​

JavaScript (Node.js)​

Usage Notes​

Interactive API Explorer​