Create an FX Trade (New)

Overview

Creates a modern FX conversion and settlement trade order supporting both wallet-to-wallet (convertWithinWallets) and direct beneficiary payout conversions (convertWalletPayout).

HTTP Request

POST /banking/ibans/v2/fx/payments

Authentication

This endpoint requires an active Bearer JWT token in the Authorization header obtained via POST /banking/ibans/v2/users/login:

Authorization: Bearer <your_access_token>

Request Body Fields

Field	Type	Description
paymentType	str	Sample value: convertWalletPayout
sourceWalletId	int	Sample value: 11435
sourceAmount	int	Sample value: 4800
purposeId	int	Sample value: 14
vfxToken	str	Sample value: {{vfx_token}}
customPaymentReference	NoneType	Sample value: null
targetAccountId	int	Sample value: 23181
paymentId	str	Sample value: 0cc4d9f6-3456-4a63-a15d-122eae45841d

Code Examples

cURL

curl -X POST "https://api.ahrvo.network/banking/ibans/v2/fx/payments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "paymentType": "convertWalletPayout",
  "sourceWalletId": 11435,
  "sourceAmount": 4800,
  "purposeId": 14,
  "vfxToken": "{{vfx_token}}",
  "customPaymentReference": null,
  "targetAccountId": 23181,
  "paymentId": "0cc4d9f6-3456-4a63-a15d-122eae45841d"
}'

JavaScript (Axios)

import axios from 'axios';

const response = await axios.post('https://api.ahrvo.network/banking/ibans/v2/fx/payments', {
  "paymentType": "convertWalletPayout",
  "sourceWalletId": 11435,
  "sourceAmount": 4800,
  "purposeId": 14,
  "vfxToken": "{{vfx_token}}",
  "customPaymentReference": null,
  "targetAccountId": 23181,
  "paymentId": "0cc4d9f6-3456-4a63-a15d-122eae45841d"
}, {
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your_access_token>'
  }
});

console.log(response.data);

Python (Requests)

import requests

url = "https://api.ahrvo.network/banking/ibans/v2/fx/payments"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <your_access_token>" 
}
payload = {
  "paymentType": "convertWalletPayout",
  "sourceWalletId": 11435,
  "sourceAmount": 4800,
  "purposeId": 14,
  "vfxToken": "{{vfx_token}}",
  "customPaymentReference": null,
  "targetAccountId": 23181,
  "paymentId": "0cc4d9f6-3456-4a63-a15d-122eae45841d"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response (200)

{
  "statusCode": 200,
  "id": "20088",
  "reference": "EN-05062024-055",
  "userId": "2289",
  "companyId": "2233",
  "currencyFrom": "USD",
  "amountFrom": 4800,
  "currencyTo": "NGN",
  "amountTo": 4936560,
  "rate": 1028.4456,
  "pricing": {
    "overageFee": 0,
    "usageId": "6660409cc733e0fac55eb97f",
    "subscriptionId": "664b3fc0e8e52032427e0b70"
  },
  "state": "inwardSettlementDone",
  "source": "wallet",
  "sourceId": 11435,
  "target": "account",
  "targetId": 32655,
  "description": null,
  "inwardSettlementTime": "2024-06-05T10:40:44.000Z",
  "outwardSettlementTime": null,
  "purpose": "Professional fees payment(i.e. legal, accountant)",
  "scheduledAt": null,
  "expiredAt": null,
  "createdAt": "2024-06-05T10:40:29.000Z",
  "updatedAt": "2024-06-05T10:40:51.000Z",
  "transaction": {
    "receiver": {
      "accountNumber": "5401662301",
      "bankName": "Providus Bank",
      "name": "crest ",
      "bankCode": "000023"
    },
    "shortURL": "https://pay.vertofx.com/n3hjz2v"
  }
}

Interactive API Explorer

Test this endpoint live against the Ahrvo gateway and Verto sandbox environments: