Get an FX Trade (New)

Overview

Retrieve the details of a specific FX trade using the Ahrvo transaction reference number or payment ID. This endpoint provides complete details including settlement times, transaction details, and current state.

Resource Access

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

Path Parameters

Parameter	Type	Required	Description
reference	string	Yes	The FX trade reference number, wallet payment reference, or paymentId

Response

Success Response (200 OK)

{
  "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"
  },
  "paymentId": "88ba34cd-7074-46f4-a006-4fd8c7a5e1e8"
}

Response Fields

Field	Type	Description
id	string	Unique trade identifier
reference	string	Ahrvo reference number for this trade
userId	string	User ID who initiated the trade
companyId	string	Company ID associated with the trade
currencyFrom	string	Currency being sold/exchanged
amountFrom	number	Amount sold/exchanged
currencyTo	string	Currency being bought
amountTo	number	Amount received
rate	number	Exchange rate applied
pricing.overageFee	number	Fee for exceeding usage limits
pricing.usageId	string	Usage tracking identifier
pricing.subscriptionId	string	Subscription plan identifier
state	string	Current state of the trade
source	string	Source entity type (wallet/account)
sourceId	string	Source entity identifier
target	string	Target entity type (wallet/account)
targetId	string	Target entity identifier
inwardSettlementTime	string (date-time)	When sender's account was debited
outwardSettlementTime	string (date-time)	When receiver's account was credited
purpose	string	Purpose of the trade
scheduledAt	string	Scheduled execution time (if applicable)
expiredAt	string	Expiration timestamp (if applicable)
createdAt	string (date-time)	Trade creation timestamp
updatedAt	string (date-time)	Last update timestamp
transaction.receiver	object	Receiver's bank account details
transaction.shortURL	string	Short URL for the trade
paymentId	string	UUID of the associated payment

Trade States

State	Description
confirmed	Trade has been confirmed
inwardSettlementDone	Sender's account has been debited
outwardSettlementDone	Receiver's account has been credited
inwardSettlementPending	Awaiting inward settlement
outwardSettlementPending	Awaiting outward settlement

Error Responses

• 400 Bad Request: Invalid reference format
• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Trade not found for the given reference
• 500 Internal Server Error: Server error

Code Examples

cURL

curl -X GET \
  'https://gateway.ahrvo.network/banking/ibans/v2/fx/EN-05062024-055' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Python

import requests

reference = "EN-05062024-055"
url = f"https://gateway.ahrvo.network/banking/ibans/v2/fx/{reference}"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

response = requests.get(url, headers=headers)
trade = response.json()
print(f"Trade state: {trade['state']}, Rate: {trade['rate']}")

JavaScript (Node.js)

const axios = require('axios');

const reference = 'EN-05062024-055';
const url = `https://gateway.ahrvo.network/banking/ibans/v2/fx/${reference}`;
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
};

axios.get(url, { headers })
  .then(response => {
    console.log('Trade state:', response.data.state);
    console.log('Amount converted:', response.data.amountFrom, response.data.currencyFrom, '→', response.data.amountTo, response.data.currencyTo);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Usage Notes

• The reference path parameter accepts either the Ahrvo reference number (e.g., EN-05062024-055), wallet payment reference, or the paymentId UUID
• Use this endpoint to track individual trade progress and settlement status
• Store the reference or paymentId after creating a trade for future lookups

Interactive API Explorer