Create Payment

Overview

Make a payment to a bank account or to another Ahrvo account. The required parameters vary based on:

• Payment destination (bank account vs Ahrvo account)
• Currency requirements (same currency vs currency conversion needed)
• POBO (Pay On Behalf Of) requirements

Resource Access

• HTTP Method: POST
• Endpoint: /banking/iban/api/payout/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

{
  "biz_id": "VA202501142006502111",
  "payout_type": "PAYOUT",
  "purpose_code": "1001",
  "origin_currency": "USD",
  "target_currency": "INR",
  "target_amount": 123.45,
  "rate_id": "202501092053115499258",
  "partner_order_id": "2024834713M3STH",
  "partner_user_id": "2024834713M3STH",
  "reference": "Invoice payment",
  "to_account_id": "R202412311029369694",
  "use_pobo": "Y",
  "pobo_id": "M2023498278424",
  "clearing_network": "SWIFT",
  "payment_method": "CROSS-BORDER",
  "fee_bear": "OUR"
}

Request Fields

Field	Type	Required	Description
biz_id	string	Yes	Virtual account ID to debit from
payout_type	string	Yes	Type of payout: PAYOUT or REFUND
purpose_code	string	Yes	Purpose code for the payment
origin_currency	string	Yes	Source currency code
target_currency	string	Yes	Destination currency code
target_amount	number	Yes	Amount to send
rate_id	string	Conditional	Exchange rate ID (required for FX)
partner_order_id	string	Yes	Your unique payment identifier
partner_user_id	string	No	Your user identifier
reference	string	No	Payment reference/description
to_account_id	string	Yes	Recipient account ID
use_pobo	string	No	Use Pay On Behalf Of: Y or N
pobo_id	string	Conditional	POBO ID (required if use_pobo is Y)
clearing_network	string	No	Clearing network: SWIFT, LOCAL, SEPA
payment_method	string	No	Payment method
fee_bear	string	No	Fee bearing party: OUR, SHA, BEN

Response

Success Response (201 Created)

{
  "order_id": "202501092053115499258",
  "partner_order_id": "2024834713M3STH",
  "status": "PROCESSING",
  "biz_id": "VA202501142006502111",
  "origin_currency": "USD",
  "origin_amount": 100.00,
  "target_currency": "INR",
  "target_amount": 123.45,
  "exchange_rate": 83.25,
  "fee": 5.00,
  "created_at": "2026-01-14T10:00:00.000Z",
  "estimated_arrival": "2026-01-15T10:00:00.000Z"
}

Response Fields

Field	Type	Description
order_id	string	Unique payment order ID
partner_order_id	string	Your payment identifier
status	string	Payment status
biz_id	string	Virtual account ID
origin_currency	string	Source currency
origin_amount	number	Amount debited
target_currency	string	Destination currency
target_amount	number	Amount credited
exchange_rate	number	Applied exchange rate
fee	number	Transaction fee
created_at	string (date-time)	Creation timestamp
estimated_arrival	string (date-time)	Estimated delivery time

Payment Status Values

• PROCESSING: Payment submitted and being processed
• COMPLETED: Payment successfully delivered
• FAILED: Payment failed
• CANCELLED: Payment cancelled

Error Responses

• 400 Bad Request: Invalid input data
• 401 Unauthorized: Invalid or missing authentication token
• 402 Insufficient Balance: Insufficient funds in virtual account
• 404 Not Found: Recipient or virtual account not found
• 422 Unprocessable Entity: Validation errors

Code Examples

cURL

curl -X POST \
  'https://gateway.ahrvo.network/banking/iban/api/payout/v2/create' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "biz_id": "VA202501142006502111",
    "payout_type": "PAYOUT",
    "purpose_code": "1001",
    "origin_currency": "USD",
    "target_currency": "INR",
    "target_amount": 123.45,
    "partner_order_id": "2024834713M3STH",
    "to_account_id": "R202412311029369694",
    "fee_bear": "OUR"
  }'

Python

import requests

url = "https://gateway.ahrvo.network/banking/iban/api/payout/v2/create"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "biz_id": "VA202501142006502111",
    "payout_type": "PAYOUT",
    "purpose_code": "1001",
    "origin_currency": "USD",
    "target_currency": "INR",
    "target_amount": 123.45,
    "partner_order_id": "2024834713M3STH",
    "to_account_id": "R202412311029369694",
    "fee_bear": "OUR"
}

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/payout/v2/create';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};
const data = {
  biz_id: 'VA202501142006502111',
  payout_type: 'PAYOUT',
  purpose_code: '1001',
  origin_currency: 'USD',
  target_currency: 'INR',
  target_amount: 123.45,
  partner_order_id: '2024834713M3STH',
  to_account_id: 'R202412311029369694',
  fee_bear: 'OUR'
};

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

Usage Notes

• Ensure sufficient balance in the source virtual account
• Recipient must have AVAILABLE status
• Use unique partner_order_id for idempotency
• Store the order_id for tracking and queries
• Monitor payment status via webhooks or polling
• FX payments require a valid rate_id
• Fee bearer determines who pays transaction fees

Fee Bearer Options

• OUR: Sender pays all fees
• SHA: Fees shared between sender and recipient
• BEN: Recipient pays all fees

Interactive API Explorer