Create FX Trade (Atlas)

Overview

The POST /banking/ibans/v2/fx/payments endpoint executes a foreign exchange trade using funds from your multi-currency wallets.

The request payload supports two distinct workflows using the paymentType discriminator:

1. convertWithinWallets: Converts funds from one of your wallets (or multiple funding sources) and deposits the converted amount into another wallet belonging to your organization.
2. convertWalletPayout: Converts wallet funds and routes the proceeds directly to an external beneficiary bank account or mobile wallet (targetAccountId).

[!IMPORTANT] To execute a trade, you must provide a valid, non-expired vfxToken obtained from POST /banking/ibans/v2/fx/quote. This guarantees the agreed conversion rate.

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/fx/payments
• Authentication: Bearer token required

Request Headers

Header	Value	Required	Description
Authorization	Bearer {access_token}	Yes	JWT Bearer access token
Content-Type	application/json	Yes	Request payload format
Accept	application/json	Yes	Response payload format

Request Body

Schema 1: Convert Within Wallets (convertWithinWallets)

Field	Type	Required	Description
paymentType	string	Yes	Must be convertWithinWallets.
vfxToken	string	Yes	Rate-locking token returned by POST /banking/ibans/v2/fx/quote.
sourceWalletId	number	Conditional	ID of the funding wallet. Use either sourceWalletId or sources.
sources	array	Conditional	Array of { walletId, amount } objects for multi-wallet funding.
sourceAmount	number	Conditional	Amount to sell. Provide either sourceAmount or targetAmount.
targetAmount	number	Conditional	Amount to buy. Provide either sourceAmount or targetAmount.
targetWalletId	number	Yes	ID of the recipient wallet where converted funds are deposited.
paymentId	string (UUID)	No	Client idempotency UUID to prevent duplicate executions.
customPaymentReference	string	No	Optional client reference tag.

Schema 2: Convert and Pay Out (convertWalletPayout)

Field	Type	Required	Description
paymentType	string	Yes	Must be convertWalletPayout.
vfxToken	string	Yes	Rate-locking token returned by POST /banking/ibans/v2/fx/quote.
sourceWalletId	number	Conditional	ID of the source wallet funding the payout.
targetAccountId	number	Yes	ID of the beneficiary account receiving the converted payout.
purposeId	number	Yes	Purpose of payment identifier (required for compliance routing).
sender	object	No	Originator entity details (country, name, `type: individual

Request Examples

1. Convert Within Own Wallets

{
  "paymentType": "convertWithinWallets",
  "vfxToken": "vfx_9f83a28c11e04812b7fa128471203",
  "sourceWalletId": 101,
  "sourceAmount": 5000.00,
  "targetWalletId": 202,
  "paymentId": "550e8400-e29b-41d4-a716-446655440000",
  "customPaymentReference": "Q3-Treasury-Rebalance"
}

2. Convert and Pay Out to Beneficiary

{
  "paymentType": "convertWalletPayout",
  "vfxToken": "vfx_9f83a28c11e04812b7fa128471203",
  "sourceWalletId": 101,
  "sourceAmount": 12500.00,
  "targetAccountId": 948201,
  "purposeId": 1,
  "paymentId": "771e8400-e29b-41d4-a716-446655440099",
  "customPaymentReference": "Supplier-Invoice-982"
}

Response

Success Response (200 OK)

{
  "id": "10492",
  "reference": "EN-01011900-001",
  "currencyFrom": "USD",
  "amountFrom": 5000.00,
  "currencyTo": "GBP",
  "amountTo": 3927.00,
  "rate": 0.7854,
  "state": "confirmed",
  "source": "wallet",
  "sourceId": 101,
  "target": "wallet",
  "targetId": 202,
  "createdAt": "2026-09-16T02:00:00.000Z",
  "tracking": {
    "uetr": "dd60300f-25e6-4fb3-bb87-36ceb02844f2"
  }
}

Response Fields

Field	Type	Description
id	string	Unique internal order identifier.
reference	string	Public trade reference (e.g. EN-01011900-001).
state	string	Trade execution state: initiated, confirmed, inwardSettlementDone, outwardSettlementDone.
amountFrom	number	Amount debited in source currency.
amountTo	number	Amount credited in target currency.
rate	number	Effective exchange rate executed.
tracking.uetr	string	Unique End-to-End Transaction Reference for international settlement tracking.

Error Responses

• 400 Bad Request: Expired vfxToken, insufficient wallet balance, or missing mandatory fields.
• 401 Unauthorized: Missing or expired Bearer token.
• 403 Forbidden: Access denied to source wallet or target account.
• 500 Internal Server Error: Trade execution gateway error.

Code Examples

cURL

curl -X POST "https://gateway.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",
    "vfxToken": "vfx_9f83a28c11e04812b7fa128471203",
    "sourceWalletId": 101,
    "sourceAmount": 5000.00,
    "targetWalletId": 202
  }'

Python

import requests

url = "https://gateway.ahrvo.network/banking/ibans/v2/fx/payments"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

payload = {
    "paymentType": "convertWithinWallets",
    "vfxToken": "vfx_9f83a28c11e04812b7fa128471203",
    "sourceWalletId": 101,
    "sourceAmount": 5000.00,
    "targetWalletId": 202
}

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

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/ibans/v2/fx/payments';
const headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};

const payload = {
  paymentType: 'convertWithinWallets',
  vfxToken: 'vfx_9f83a28c11e04812b7fa128471203',
  sourceWalletId: 101,
  sourceAmount: 5000.00,
  targetWalletId: 202
};

axios.post(url, payload, { headers })
  .then(res => console.log('Order Reference:', res.data.reference))
  .catch(err => console.error(err.response ? err.response.data : err.message));

Interactive API Explorer