Create Instant FX Conversion

Overview

Create instant foreign exchange (FX) conversions between supported currencies. Transactions are conducted based on a rate_id obtained from the FX quote endpoint. Transactions can be executed at the quoted rate within its validity period.

Resource Access

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

{
  "sell_currency": "USD",
  "buy_currency": "CNH",
  "sell_amount": 1,
  "rate_id": "8457823465836486583",
  "payment_mode": "BALANCE",
  "request_id": "202409021603FW00001",
  "conversion_type": "T0"
}

Request Fields

Field	Type	Required	Description
sell_currency	string	Yes	Currency to sell (3-letter ISO code)
buy_currency	string	Yes	Currency to buy (3-letter ISO code)
sell_amount	number	Yes	Amount to sell (2 decimals, JPY integers only)
rate_id	string	Yes	Rate ID from FX quote endpoint
payment_mode	string	Yes	Payment mode: BALANCE or BANK_TRANSFER
request_id	string	Yes	Unique request identifier for idempotency
conversion_type	string	Yes	Conversion type: T0 (instant), T1, or T2

Response

Success Response (201 Created)

{
  "transaction_id": "FX202501140001234567",
  "request_id": "202409021603FW00001",
  "status": "COMPLETED",
  "sell_currency": "USD",
  "buy_currency": "CNH",
  "sell_amount": 1.00,
  "buy_amount": 7.25,
  "exchange_rate": 7.25,
  "created_at": "2026-01-14T10:00:00.000Z"
}

Response Fields

Field	Type	Description
transaction_id	string	Unique FX transaction ID
request_id	string	Your request identifier
status	string	Transaction status
sell_currency	string	Currency sold
buy_currency	string	Currency bought
sell_amount	number	Amount sold
buy_amount	number	Amount received
exchange_rate	number	Applied exchange rate
created_at	string (date-time)	Transaction timestamp

Transaction Status Values

• PENDING: Transaction initiated
• PROCESSING: Transaction in progress
• COMPLETED: Transaction successful
• FAILED: Transaction failed

Error Responses

• 400 Bad Request: Invalid input data or currency pair
• 401 Unauthorized: Invalid or missing authentication token
• 402 Insufficient Balance: Insufficient funds for conversion
• 410 Gone: Rate expired - rate_id no longer valid

Code Examples

cURL

curl -X POST \
  'https://gateway.ahrvo.network/banking/iban/api/fx/v2/transaction/create' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "sell_currency": "USD",
    "buy_currency": "CNH",
    "sell_amount": 1,
    "rate_id": "8457823465836486583",
    "payment_mode": "BALANCE",
    "request_id": "202409021603FW00001",
    "conversion_type": "T0"
  }'

Python

import requests

url = "https://gateway.ahrvo.network/banking/iban/api/fx/v2/transaction/create"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "sell_currency": "USD",
    "buy_currency": "CNH",
    "sell_amount": 1,
    "rate_id": "8457823465836486583",
    "payment_mode": "BALANCE",
    "request_id": "202409021603FW00001",
    "conversion_type": "T0"
}

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/fx/v2/transaction/create';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};
const data = {
  sell_currency: 'USD',
  buy_currency: 'CNH',
  sell_amount: 1,
  rate_id: '8457823465836486583',
  payment_mode: 'BALANCE',
  request_id: '202409021603FW00001',
  conversion_type: 'T0'
};

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

Usage Notes

• Rate Validity: Execute transactions within the rate's validity period (typically 15 seconds)
• Amount Precision: JPY supports integers only; other currencies support 2 decimal places
• Idempotency: Use unique request_id to prevent duplicate conversions
• Balance Check: Ensure sufficient balance in sell currency before conversion
• Conversion Types:
  • T0: Instant conversion (same day)
  • T1: Next business day settlement
  • T2: Two business days settlement

Best Practices

1. Always obtain a fresh quote before creating a conversion
2. Store the transaction_id for tracking and reconciliation
3. Handle rate expiration errors gracefully
4. Implement retry logic for network failures
5. Monitor conversion status via webhooks

Interactive API Explorer