Apply for Virtual Account

Overview

Use this endpoint to apply for Virtual Accounts (VAs) to start receiving funds. You can only apply for VAs when the kyc_status of your account is APPROVED.

Resource Access

• HTTP Method: POST
• Endpoint: /banking/iban/api/virtual-account/v2/apply
• 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:

{
  "account_purpose": "02",
  "currency": "USD",
  "bank_location": "US"
}

Request Fields

Field	Type	Required	Description
account_purpose	string	Yes	Purpose code for the virtual account
currency	string	Yes	Currency code (ISO 4217) - USD, EUR, GBP, etc.
bank_location	string	Yes	Bank location country code (ISO 2-letter)

Response

Success Response (201 Created)

{
  "biz_id": "VA202501142006502111",
  "account_purpose": "02",
  "currency": "USD",
  "bank_location": "US",
  "account_number": "1234567890",
  "routing_number": "021000021",
  "swift_code": "CHASUS33",
  "status": "PENDING",
  "created_at": "2026-01-14T10:00:00.000Z"
}

Response Fields

Field	Type	Description
biz_id	string	Unique virtual account identifier assigned by the system
account_purpose	string	Purpose code for the virtual account
currency	string	Currency code
bank_location	string	Bank location country code
account_number	string	Virtual account number
routing_number	string	Routing number (for US accounts)
swift_code	string	SWIFT/BIC code
status	string	Application status
created_at	string (date-time)	Application creation timestamp

Account Status Values

• PENDING: Application submitted and under review
• APPROVED: Virtual account approved and active
• DECLINED: Application declined

Error Responses

• 400 Bad Request: Invalid input data (invalid currency, missing required fields)
• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: KYC status not APPROVED
• 409 Conflict: Virtual account already exists

Code Examples

cURL

curl -X POST \
  'https://gateway.ahrvo.network/banking/iban/api/virtual-account/v2/apply' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_purpose": "02",
    "currency": "USD",
    "bank_location": "US"
  }'

Python

import requests

url = "https://gateway.ahrvo.network/banking/iban/api/virtual-account/v2/apply"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "account_purpose": "02",
    "currency": "USD",
    "bank_location": "US"
}

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/virtual-account/v2/apply';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};
const data = {
  account_purpose: '02',
  currency: 'USD',
  bank_location: 'US'
};

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

Usage Notes

• You must have an APPROVED KYC status before applying for virtual accounts
• Virtual accounts allow you to receive funds in multiple currencies
• Each currency and bank location combination requires a separate application
• Store the biz_id returned for future reference and operations
• Monitor application status via webhooks or polling this endpoint
• Virtual accounts are typically approved within 1-2 business days

Supported Currencies and Locations

Currency	Supported Locations
USD	US
EUR	DE, FR, IT, ES, NL
GBP	GB
CNY	CN
INR	IN

Next Steps

After applying for a virtual account:

1. Monitor the status via webhooks or status check endpoint
2. Once APPROVED, use the account details to receive funds
3. View received funds in your ledger
4. Create recipients for outbound payments

Interactive API Explorer