Create FX Trade (New)

Overview

Create an FX trade between all the currency pairs we support. You can convert funds into another wallet or send the converted funds directly to a beneficiary. This API requires a valid vfx_Token obtained from the Get Rates endpoint.

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/fx/payments
• 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
x-api-key	string	No	API key for additional authentication

Request Body

{
  "paymentType": "convertWalletPayout",
  "sourceWalletId": 11435,
  "sourceAmount": 4800,
  "purposeId": 45,
  "vfx_Token": "uciebcjdencijwnijnciqnq832982jhbj3eduh3",
  "customPaymentReference": "Payment to Jonas computers",
  "targetAccountId": 839,
  "paymentId": "35448e78-8180-4ce5-8671-772c29ad658f",
  "supportingDocS3Key": "",
  "sender": {
    "country": "NG",
    "type": "company",
    "name": "Suit Country",
    "customerIdentificationNumber": "45jtjy",
    "accountNumber": "1234567890",
    "address_line_1": "house street",
    "address_city": "London",
    "origination_country": "US",
    "zip_code": "83888",
    "registration_country": "NG",
    "companyRegistrationNumber": "7575788",
    "sub_category": "Baby products"
  }
}

Request Fields

Field	Type	Required	Description
paymentType	string	Yes	convertWalletPayout (to beneficiary) or convertWithinWallets (to wallet)
sourceWalletId	number	Yes	Wallet ID to deduct funds from
sourceAmount	number	Yes	Amount to deduct from the source wallet
purposeId	number	Conditional	Purpose code. Required for convertWalletPayout
vfx_Token	string	Yes	Rate token from Get Rates endpoint. Valid for 30 seconds
customPaymentReference	string	No	Custom reference to store for this payment
targetAccountId	number	Conditional	Beneficiary ID. Required for convertWalletPayout
targetWalletId	number	Conditional	Wallet ID. Required for convertWithinWallets
paymentId	string (UUID)	Yes	Unique payment identifier for idempotency
supportingDocS3Key	string	No	S3 key for supporting document
sender	object	No	Underlying sender details for compliance
sender.type	string	No	Sender type: company or individual
sender.country	string	No	Country of origin of funds
sender.name	string	No	Full name of the sender
sender.dob	string	No	Date of birth (individuals only)
sender.nationality	string	No	Nationality (individuals only)

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,
  "pricing": {
    "overageFee": 0,
    "usageId": "6660409cc733e0fac55eb97f",
    "subscriptionId": "664b3fc0e8e52032427e0b70"
  },
  "state": "inwardSettlementDone",
  "source": "wallet",
  "sourceId": 11435,
  "target": "account",
  "targetId": 32655,
  "inwardSettlementTime": "2024-06-05T10:40:44.000Z",
  "outwardSettlementTime": null,
  "purpose": "Professional fees payment",
  "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.Ahrvofx.com/n3hjz2v"
  }
}

Response Fields

Field	Type	Description
id	string	Unique trade identifier
reference	string	Ahrvo unique reference number
currencyFrom	string	Source currency converted from
amountFrom	number	Source amount
currencyTo	string	Target currency
amountTo	number	Target amount received
rate	number	Exchange rate applied
state	string	Current state of the trade
source	string	Source entity type (wallet/account)
target	string	Target entity type (wallet/account)
inwardSettlementTime	string (date-time)	When sender was debited
outwardSettlementTime	string (date-time)	When receiver was credited
transaction.receiver	object	Receiver's bank details
transaction.shortURL	string	Short URL for the trade

Error Responses

• 400 Bad Request: Invalid request data
• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Beneficiary or wallet not found
• 500 Internal Server Error: Server error

Code Examples

cURL

curl -X POST \
  'https://gateway.ahrvo.network/banking/ibans/v2/fx/payments' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "paymentType": "convertWalletPayout",
    "sourceWalletId": 11435,
    "sourceAmount": 4800,
    "purposeId": 45,
    "vfx_Token": "YOUR_VFX_TOKEN",
    "targetAccountId": 839,
    "paymentId": "35448e78-8180-4ce5-8671-772c29ad658f"
  }'

Python

import requests

url = "https://gateway.ahrvo.network/banking/ibans/v2/fx/payments"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "paymentType": "convertWalletPayout",
    "sourceWalletId": 11435,
    "sourceAmount": 4800,
    "purposeId": 45,
    "vfx_Token": "YOUR_VFX_TOKEN",
    "targetAccountId": 839,
    "paymentId": "35448e78-8180-4ce5-8671-772c29ad658f"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(f"Trade ID: {result['id']}, Reference: {result['reference']}")

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/ibans/v2/fx/payments';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};
const data = {
  paymentType: 'convertWalletPayout',
  sourceWalletId: 11435,
  sourceAmount: 4800,
  purposeId: 45,
  vfx_Token: 'YOUR_VFX_TOKEN',
  targetAccountId: 839,
  paymentId: '35448e78-8180-4ce5-8671-772c29ad658f'
};

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

Usage Notes

• Always obtain a fresh vfx_Token from Get Rates immediately before creating a trade
• The vfx_Token expires in 30 seconds — execute the trade within this window
• Use a unique paymentId (UUID) for each trade to ensure idempotency
• For convertWalletPayout, both purposeId and targetAccountId are required
• For convertWithinWallets, targetWalletId is required instead
• Include sender details for regulatory compliance when required

Payment Type Guide

paymentType	Description	Required Fields
convertWalletPayout	Convert and send to a beneficiary account	purposeId, targetAccountId
convertWithinWallets	Convert and move to another wallet	targetWalletId

Interactive API Explorer