VertoFX API - Technical Integration Guide

Introduction

Welcome to the VertoFX Platform API technical integration guide.

VertoFX is a leading B2B cross-border payments, multi-currency account, and foreign exchange (FX) infrastructure provider. Through the Ahrvo Banking platform integration, businesses can seamlessly:

• Create and manage multi-currency accounts & wallets across 25+ global and emerging market currencies (USD, GBP, EUR, NGN, KES, ZAR, INR, CAD, etc.).
• Obtain real-time streaming FX quotes with competitive institutional spreads and secure time-locked quote tokens.
• Execute binding FX conversion orders within wallets or directly into international bank beneficiaries.
• Manage beneficiary lifecycles with automated routing, SWIFT/BIC verification, and confirmation of payee.
• Initiate automated payout and withdrawal requests with real-time tracking, idempotent execution, and proof-of-payment generation.
• Receive real-time event webhooks for payment status updates, FX confirmations, and beneficiary compliance approvals.

---

Core API Architecture

The VertoFX API ecosystem is structured into six functional modules:

graph TD
    Auth["1. Authentication (/users/login)"] --> FX["2. Foreign Exchange (/fx, /orders/v2.1/fx)"]
    Auth --> Bene["3. Beneficiaries (/profile/v2.1/beneficiaries)"]
    Auth --> Wallets["4. Wallets & Transfers (/profile/v2.1/wallets, /transfer)"]
    Auth --> Payout["5. Payment Requests (/profile/v2.1/request)"]
    Auth --> Ref["6. Reference Data (/profile/v2.1/purpose, /currencies)"]
    
    FX --> Wallets
    Bene --> Payout
    Wallets --> Payout

Module	Description	Primary Endpoints
Authentication	API Key & Client ID exchange for short-lived Bearer tokens	POST /banking/ibans/v2/users/login
Foreign Exchange (FX)	Real-time rate quotation, tokenized lock-ins, and trade execution	POST /banking/ibans/v2/fx/rate, POST /banking/ibans/v2/fx/payments, GET /banking/ibans/v2/orders/v2.1/fx
Beneficiary Management	Recipient registration, domestic/SWIFT routing, and account updates	POST /banking/ibans/v2/profile/v2.1/beneficiaries, GET /banking/ibans/v2/profile/v2.1/beneficiaries
Wallets & Transfers	Multi-currency balance management and instant intra-wallet transfers	GET /banking/ibans/v2/profile/v2.2/wallets, POST /banking/ibans/v2/transfer
Payment Requests	Automated disbursement requests and status tracking	POST /banking/ibans/v2/profile/v2.2/request, GET /banking/ibans/v2/profile/v2.1/request/{id}
Reference Data	Standardized international purpose codes and supported currency pairs	GET /banking/ibans/v2/profile/v2.1/purpose, GET /banking/ibans/v2/profile/v2.1/currencies

---

Environments & Base URLs

Environment	Base URL	Description
Production (Ahrvo Gateway)	https://api.ahrvo.network	Primary production API gateway
Staging (Ahrvo Sandbox)	https://gateway.ahrvo.network	Sandbox testing gateway
Verto Sandbox	https://api-v3-sandbox.vertofx.com	Direct VertoFX testing cluster

---

Authentication Flow

All private endpoints require an Authorization header containing a valid Bearer JWT:

Authorization: Bearer <your_access_token>

Token Lifecycle

1. Send your clientId and apiKey to POST /banking/ibans/v2/users/login:

   {
     "clientId": "YOUR_CLIENT_ID",
     "apiKey": "YOUR_API_KEY",
     "mode": "apiKey"
   }

2. The server responds with a JWT token valid for 60 minutes (3600 seconds).
3. Include the token in subsequent API requests.
4. Refresh your token before the 60-minute expiry to ensure uninterrupted service.

[!TIP] Keep your apiKey secure. For security reasons, generated API keys are only displayed once in the merchant portal. If an API key is lost, generate a new key immediately.

---

Webhooks & Event Notifications

VertoFX emits asynchronous HTTPS webhooks for critical lifecycle events. Configure your receiving endpoint in the developer portal to handle automatic status synchronizations.

Captured Event Types

Event Trigger	Event Identifier (event)	Status Field	Description
Payment Request Initiated	PAYMENT_STATUS_CHANGE	requested	Funds withdrawal request received and queued
Payment Completed	PAYMENT_STATUS_CHANGE	completed	Payout cleared and delivered to recipient bank
Payment Refunded	PAYMENT_STATUS_CHANGE	refunded	Payout failed; funds returned to corporate wallet
FX Trade Confirmed	FX_STATUS_CHANGE	completed	Conversion executed and settlement balances credited
Beneficiary Approved	BENEFICIARY_STATUS_CHANGE	approved	Recipient validated by compliance and ready for payouts
Beneficiary Rejected	BENEFICIARY_STATUS_CHANGE	rejected	Recipient failed compliance/sanction screening

Retry Policy

• If your webhook listener does not return an HTTP 200 OK within 10 seconds, Verto automatically retries delivery up to 10 times throughout the day using an exponential backoff algorithm.
• Ensure your endpoint is idempotent by checking incoming transaction and reference IDs.

---

Frequently Asked Questions (FAQ)

1. How does the side parameter work in Create FX Trade?

When quoting currencies (e.g. USD to GBP), specifying amount: 1000 could mean either:

• Sell 1,000 USD to receive GBP (side: SELL).
• Buy 1,000 GBP by selling the required USD (side: BUY). Specifying side resolves any ambiguity and ensures exact target or source funding.

2. What are the lifecycle statuses for Payment Requests?

• requested: Payment request received successfully and currently queued for processing.
• completed: Payout successfully settled and dispatched to the recipient's bank.
• refunded: Payment could not be completed; original funds returned to source wallet.
• archived: Payment cancelled by user or expired prior to execution.

3. How do I know when a newly created beneficiary is ready for payouts?

New beneficiaries may be subject to compliance review. Query GET /banking/ibans/v2/profile/v2.1/beneficiaries or listen for the BENEFICIARY_STATUS_CHANGE webhook with status approved. Initiating a payment to a non-approved beneficiary will result in a beneficiary_not_found error.

4. What are the mandatory fields for USD Beneficiaries?

• Domestic ACH / Wire: Account Number, Routing Number (ABA Code), Bank Name, Beneficiary Address, City, State/Province, and Postal Code.
• International SWIFT Wire: Account Number, SWIFT/BIC Code, Bank Name, and full Physical Address.

5. What is the nationalId field used for?

The nationalId field accepts the routing code corresponding to the destination banking jurisdiction:

• UK: Sort Code (6 digits)
• USA: ABA / Routing Number (9 digits)
• India: IFSC Code (11 alphanumeric characters)
• International: SWIFT / BIC Code (8 or 11 characters)

6. How do I handle 30-second quote token expiration?

FX quote tokens (vfxToken / vfx_token) expire after 30 seconds to protect against currency market fluctuations. If an order cannot be booked within 30 seconds, request a new quote immediately before booking. Maintain pre-funded wallets to ensure zero delay.

---

Change Log (v2.1 & v2.2)

• Payment Requests: Added paymentId idempotency key to prevent double debit scenarios.
• Exchange Now (/fx/*): Introduced modern /fx/rate, /fx/payments, and /fx/list endpoints supporting wallet-to-wallet and wallet-to-payout conversions.
• Beneficiaries: Added clientReference field for custom reconciliation; automated bank routing resolution via nationalId.
• Wallets v2.2: Enhanced wallet details endpoint returning real-time reserve balances, pending settlement ledger, and funding methods.