1. Guides
CrossFX Payment APIs
  • Guides
    • CrossFX API Documentation
    • Support & Contact
    • API Basics
    • Authentication Guide
    • FX Rates
      • FX Rates Guide
    • Corridors
      • Supported Corridors Guide
    • Banks
      • Fetching Banks List Guide
      • Fetching Bank Branches Guide
    • Sanctions
      • Sanctions Screening Guide
    • Beneficiaries
      • Create Beneficiary Guide
      • Get Beneficiary Guide
    • Transfers
      • Generate Quote Guide
      • Confirm Transfer Guide
      • Get Transfer Status Guide
    • Crypto Deposit Address
      • Crypto Deposit Address Guide
    • Payments
      • Initiate Deposit Guide
      • Initiate Payout Guide
    • Webhooks
      • Webhooks Guide
      • Webhook Subscriptions Guide
      • Webhook Events Guide
      • Webhook Delivery Attempts Guide
    • Sandbox
      • Sandbox Data & Testing Guide
  1. Guides

CrossFX API Documentation

CROSSFX API
FX and settlement infrastructure for emerging markets.
Connect pricing, liquidity, FX execution and settlement through one API integration.
CrossFX is built for regulated PSPs and financial institutions. Your product owns the customer experience; CrossFX provides the infrastructure behind the transaction.
PricingFX executionLiquiditySettlement

Both directions. One integration.#

CrossFX sits behind your existing payment product, providing FX and settlement infrastructure for global-to-local and local-to-global flows.
INBOUND · GLOBAL → LOCAL
Global settlement value into local currency
USD / stablecoin
→
CrossFX
→
Local currency
Exchange supported global settlement value into local currency and settle to a verified beneficiary. In the current API model, beneficiaries can be bank accounts (BANK) or mobile money wallets (MMO).
OUTBOUND · LOCAL → GLOBAL
Local currency into global settlement value
Local currency
→
CrossFX
→
USD / stablecoin
CrossFX also positions the platform for the reverse direction. Use the API Reference and your configured corridors for the exact implementation available to your integration.
Flow direction: Inbound and Outbound describe the commercial direction of the FX and settlement flow. They do not imply separate endpoint sequences unless those sequences are defined in the API Reference for your integration.

Where CrossFX sits#

Your application remains the interface for your customers and operations teams. CrossFX sits behind it as the infrastructure layer connecting a transaction to FX, funding and settlement.
YOUR ENVIRONMENT
Your product
Application · platform · operations
API→
INFRASTRUCTURE
CrossFX API
Quote · transfer · funding · tracking
FX→
EXECUTION
FX + settlement
Funding · conversion · disbursement
RAILS→
DESTINATION
Payment rail
Bank · mobile money
↖ Webhooks return transaction state to your application
The exact currencies, corridors, rails and funding configuration available to you are defined by the API Reference and your CrossFX setup.

How a transaction moves#

The API lifecycle is progressive. A quote establishes the transaction context and cbtx_tracking_id; confirmation creates the transfer; funding moves it toward payout; webhooks keep your system synchronized with the resulting state.
01
Authenticate
Obtain API access
→
02
Beneficiary
Register recipient
→
03
Quote
Lock FX rate
→
04
Confirm
Create transfer
→
05
Fund
Deposit funds
→
06
Payout
Disburse locally
→
07
Track
Receive state
TRANSFER STATEpending_deposit→pending_payout→completed

What you need to integrate#

API access
Authenticate your application
The current API uses the OAuth 2.0 client-credentials grant. Send the resulting access token as a bearer token on subsequent calls.
Sandbox
Develop against test data
Use the Sandbox environment to build and validate your integration before production.
Reference data
Validate before transacting
Use corridor, bank and branch lookups so beneficiary and quote values match platform-supported data.

Integration flow#

Open each step for the implementation detail, then follow the linked guide for the exact API behaviour.
1. Authenticate
2. Create a beneficiary
3. Generate a quote
4. Confirm the transfer
5. Fund the transfer
6. Initiate the payout
7. Track the transfer

Funding and settlement#

A Deposit is the funding leg of a transfer. The current API supports stablecoin and fiat funding paths.
Stablecoin funding
USDC or USDT
Send stablecoins to a CrossFX deposit address on a supported chain.

CrossFX monitors the chain and confirms the transaction. Payout can be triggered once the required block confirmations have been reached and the transfer is ready for payout.

`Deposit address → Confirmation → Payout ready`
Fiat funding
Fiat settlement
Use the account details configured for the transfer or your integration and report the deposit with your client identifier.

The current API guide describes CrossFX receiving fiat and converting it to a stablecoin through a conversion partner before payout can proceed.

`Fiat received → Conversion → Payout ready`
Funding state is not transfer state. A deposit carries its own status; the parent transfer moves through a separate lifecycle as funding and payout legs progress.

Core concepts#

The API is centred on a Transfer. Funding, payout and any refund are represented as associated legs of that transaction.
PRIMARY RESOURCE
Transfer
cbtx_tracking_id
The FX and settlement transaction
↓
FUNDING LEG
Deposit
Funds the transfer
deposit_id
DISBURSEMENT LEG
Payout
Settles the beneficiary
payout_id
WHEN APPLICABLE
Refund
Returns funds when a refund is raised

Transfer#

A Transfer is the central resource for the FX and settlement transaction.
It is created from a confirmed quote and links the sender, verified beneficiary, source and destination amounts, effective FX rate and its associated transaction legs.
Its primary identifier is cbtx_tracking_id. Its current lifecycle state is held in status.

Deposit#

A Deposit describes how a transfer is funded.
It records the expected and received settlement amounts, funding method, method-specific funding details and the state of the funding leg.
Where populated, method is CRYPTO or FIAT.

Payout#

A Payout represents the disbursement leg of the transaction.
It records the amount and currency being disbursed, the beneficiary, provider reference and payout state.
A payout is initiated once funding has succeeded and the transfer is ready for payout.

Identifiers to carry through your integration#

cbtx_tracking_id
Primary transfer identifier
Issued when the quote is generated. Carry the exact value into downstream calls and use it when tracking or investigating the transaction.
beneficiary_id
Beneficiary identifier
Identifies the verified beneficiary associated with the payout.
deposit_id
Funding-leg identifier
Identifies an individual deposit associated with the transfer.
payout_id
Payout-leg identifier
Identifies an individual payout associated with the transfer.
provider_reference is also returned on deposit and payout resources where applicable and represents the underlying provider's reference for that leg.
Transfer state and leg state are different. A Transfer follows the transfer lifecycle described below. Deposit, Payout and Refund legs independently use pending, processing, succeeded or failed.
For complete field definitions, request bodies and response schemas, use the API Reference.

Lookup and reference APIs#

These APIs help you collect valid transaction data before beneficiary creation and quoting. They do not hold transfer state.
Supported Corridors Guide
Where can you transact?
Check which source and destination currency pairs can be quoted.
FX Rates Guide
What is the current rate?
Retrieve the rate for a currency pair for display before a sender commits.
Fetching Banks List Guide
Where can the beneficiary receive funds?
Retrieve supported banks for a country. Use `branch_details_required` to determine whether you need to collect a branch.
Fetching Bank Branches Guide
Which branch should be submitted?
Retrieve branches for banks that require branch details.

Transfer status lifecycle#

Transfer statuses are lowercase on the wire. Match on the exact value.

Normal progression#

pending_deposit
Await funding
Fund the transfer, then initiate the deposit.
→
pending_payout
Ready to pay
Initiate the payout.
→
pending_reconcile
Reconciliation
Wait. No action is needed.
→
completed
Complete
The beneficiary was paid.
The progression above is a compact orientation view. Always handle the exact transfer status returned by the API.

Exception and terminal states#

Failed
failed
The transfer failed.

**Action:** Read the relevant leg's `failure_reason`.
Refund lifecycle
refunding → refunded
While `refunding`, wait for the result.

`refunded` means funds were returned to the sender.

If the state becomes `refund_failed`, contact support with the `cbtx_tracking_id`.
Cancelled
cancelled
The transfer was cancelled.

**Action:** Nothing further.
The deposit, payout, and refund legs each carry their own status, one of pending, processing, succeeded, or failed.
A transfer status and a leg status are not interchangeable.

Start building#

Use the guides below to move from integration fundamentals into testing and implementation.
API Basics
Start here
Base URLs, response shapes, paging, error codes, and which calls are safe to repeat.
APIs
Explore the API Reference
Every endpoint, with request and response schemas you can call directly.
Webhooks Guide
Build asynchronous state handling
Subscribe to events, verify signatures, and handle retries.
Sandbox Data & Testing Guide
Test your integration
The reference data the Sandbox accepts and the two headers that drive responses on demand.
Sanctions Screening Guide
Understand screening behaviour
Where screening runs and how a match is returned.
Modified at 2026-09-11 11:55:59
Next
Support & Contact
Built with