Create FX Trade (New)

Overview

Execute a foreign exchange trade using the vfx_Token acquired from POST /banking/ibans/v2/fx/rate.

You can convert funds into another destination wallet (convertWithinWallets) or send converted funds directly to an external beneficiary (convertWalletPayout).

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/fx/payments
• Authentication: Bearer token required (Authorization: Bearer {access_token})

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication
Content-Type	application/json	Yes	Request body content type
x-api-key	string	No	Optional API key

Request Body

Wallet-to-Wallet Conversion (convertWithinWallets)

{
  "paymentType": "convertWithinWallets",
  "sourceWalletId": 11435,
  "sourceAmount": 4800,
  "vfx_Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.token",
  "targetWalletId": 12890,
  "paymentId": "35448e78-8180-4ce5-8671-772c29ad658f",
  "customPaymentReference": "Rebalancing EUR balance"
}

Conversion with Beneficiary Payout (convertWalletPayout)

{
  "paymentType": "convertWalletPayout",
  "sourceWalletId": 11435,
  "sourceAmount": 4800,
  "purposeId": 45,
  "vfx_Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.token",
  "targetAccountId": 839,
  "paymentId": "35448e78-8180-4ce5-8671-772c29ad658f",
  "customPaymentReference": "Invoice 2026-09 settlement"
}

Request Fields

Field	Type	Required	Description
paymentType	string	Yes	Either convertWithinWallets or convertWalletPayout.
sourceWalletId	number	Yes	ID of the source currency wallet to debit.
sourceAmount	number	Yes	Amount to convert from the source wallet.
vfx_Token	string	Yes	Rate lock token obtained from POST /banking/ibans/v2/fx/rate within the past 30 seconds.
paymentId	string (UUID)	Yes	Unique idempotency UUID to prevent duplicate executions.
targetWalletId	number	Required if convertWithinWallets	Destination wallet ID for receiving the converted currency.
targetAccountId	number	Required if convertWalletPayout	Registered beneficiary ID receiving the converted payout.
purposeId	number	Required if convertWalletPayout	Regulatory purpose of payment identifier.
customPaymentReference	string	No	Optional merchant reference identifier.

Response

Success Response (200 OK)

{
  "id": "20088",
  "reference": "EN-10052024-015",
  "userId": "2289",
  "companyId": "2233",
  "currencyFrom": "USD",
  "amountFrom": 4800,
  "currencyTo": "NGN",
  "amountTo": 4936560,
  "rate": 1028.4456,
  "status": "COMPLETED",
  "createdAt": "2026-09-15T12:00:05Z"
}

Response Fields

Field	Type	Description
id	string	Unique internal identifier for the executed trade.
reference	string	Public reference code for the FX transaction.
currencyFrom	string	Source currency code sold.
amountFrom	number	Amount debited from the source wallet.
currencyTo	string	Target currency code bought.
amountTo	number	Amount credited to the destination wallet or beneficiary.
rate	number	Final execution rate applied to the trade.
status	string	Trade execution status (COMPLETED, SETTLED, PROCESSING).
createdAt	string (ISO Date)	Execution timestamp.

Error Responses

• 400 Bad Request: Expired vfx_Token, insufficient balance in source wallet, or invalid destination wallet ID.
• 401 Unauthorized: Missing or expired access token.
• 403 Forbidden: Wallet or account restrictions.
• 500 Internal Server Error: Internal transaction processing error.

Code Examples

cURL

curl -X POST "https://api.ahrvo.network/banking/ibans/v2/fx/payments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "paymentType": "convertWithinWallets",
    "sourceWalletId": 11435,
    "sourceAmount": 4800,
    "vfx_Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.token",
    "targetWalletId": 12890,
    "paymentId": "35448e78-8180-4ce5-8671-772c29ad658f"
  }'

Python

import requests
import uuid

url = "https://api.ahrvo.network/banking/ibans/v2/fx/payments"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "paymentType": "convertWithinWallets",
    "sourceWalletId": 11435,
    "sourceAmount": 4800,
    "vfx_Token": "YOUR_VFX_TOKEN",
    "targetWalletId": 12890,
    "paymentId": str(uuid.uuid4())
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print("Trade Reference:", data.get("reference"))
print("Status:", data.get("status"))

JavaScript / Node.js

const { randomUUID } = require('crypto');

const response = await fetch("https://api.ahrvo.network/banking/ibans/v2/fx/payments", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    paymentType: "convertWithinWallets",
    sourceWalletId: 11435,
    sourceAmount: 4800,
    vfx_Token: "YOUR_VFX_TOKEN",
    targetWalletId: 12890,
    paymentId: randomUUID()
  })
});

const trade = await response.json();
console.log("Trade Reference:", trade.reference);
console.log("Settlement Status:", trade.status);

Interactive API Explorer