Query Recipient

Overview

Query the status and details of an existing recipient using either the system-assigned biz_id or your partner_user_id.

Resource Access

• HTTP Method: GET
• Endpoint: /banking/iban/api/recipient/v2/query
• Authentication: Bearer token required

Query Parameters

Parameter	Type	Required	Description
biz_id	string	Conditional	The unique recipient identifier assigned by the system
partner_user_id	string	Conditional	The unique recipient identifier in your system. Required when biz_id is not provided

Note: At least one of biz_id or partner_user_id must be provided.

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for the response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication
on-behalf-of	string	No	Customer ID for on-behalf-of operations

Response

Success Response (200 OK)

{
  "biz_id": "R202501080950209789",
  "partner_user_id": "abcd1234",
  "holder_type": "PERSONAL",
  "account_type": "RECIPIENT_BANK",
  "status": "AVAILABLE",
  "bank_detail": {
    "currency": "INR",
    "account_name": "JOHN DOE",
    "account_no": "****5678",
    "bank_name": "BANK OF BARODA",
    "bank_code": "BARB",
    "location": "IN",
    "swift_code": "BARBINBBIBK"
  },
  "recipient_detail": {
    "recipient_type": "20",
    "recipient_location": "IN",
    "email": "recipient@example.com",
    "address": "123 Street Name",
    "name": "JOHN DOE"
  },
  "created_at": "2026-01-14T10:00:00.000Z",
  "updated_at": "2026-01-14T10:00:00.000Z",
  "verification_date": "2026-01-14T12:00:00.000Z"
}

Response Fields

Field	Type	Description
biz_id	string	System recipient identifier
partner_user_id	string	Your recipient identifier
holder_type	string	Account holder type
account_type	string	Account type
status	string	Current recipient status
bank_detail	object	Banking information (account numbers masked)
recipient_detail	object	Recipient personal information
created_at	string (date-time)	Creation timestamp
updated_at	string (date-time)	Last update timestamp
verification_date	string (date-time)	Verification completion timestamp

Recipient Status Values

• PENDING: Under verification
• AVAILABLE: Verified and ready for payments
• DECLINED: Verification failed or additional information needed
• SUSPENDED: Temporarily suspended

Error Responses

• 401 Unauthorized: Invalid or missing authentication token
• 404 Not Found: Recipient not found

Code Examples

cURL

curl -X GET \
  'https://gateway.ahrvo.network/banking/iban/api/recipient/v2/query?biz_id=R202501080950209789&partner_user_id=abcd1234' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Python

import requests

url = "https://gateway.ahrvo.network/banking/iban/api/recipient/v2/query"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
params = {
    "biz_id": "R202501080950209789",
    "partner_user_id": "abcd1234"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/iban/api/recipient/v2/query';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
};
const params = {
  biz_id: 'R202501080950209789',
  partner_user_id: 'abcd1234'
};

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

Usage Notes

• Only recipients with AVAILABLE status can receive payments
• Account numbers are masked for security
• DECLINED status may include reasons for rejection
• Use webhooks to monitor recipient status changes
• Recipients can be updated if status is AVAILABLE or DECLINED

Interactive API Explorer