Overview

The Conversions API allows you to convert funds between different currencies within your organization. You can create conversions directly or by using a previously generated quote. The API supports converting between accounts in different currencies, as well as converting into FX settlement batches.

Conversion Object

A Conversion object represents a currency exchange operation. When you request a currency conversion, the system debits your source account, applies the appropriate exchange rate, and credits the destination with the converted amount.

Property	Type	Required	Description
id	string (UUID)	✅	Unique identifier of the conversion
state	string	✅	Current state of the conversion (COMPLETED, PENDING, PROCESSING, FAILED, etc.)
status_description	string	✅	Human-readable description of the conversion status
created_date	string (ISO date)	✅	Date when the conversion was created
updated_date	string (ISO date)	✅	Date when the conversion was last updated
completion_date	string (ISO date)	❌	Date when the conversion was completed (null if not completed)
internal_reference	string	✅	Internal system reference for the conversion
client_reference	string	❌	Client-defined unique reference for idempotency or reconciliation
client_metadata	object	❌	Client-provided metadata associated with the conversion
account_id	string (UUID)	✅	ID of the source account
source_amount	object	✅	Amount sold/instructed amount
source_amount.value	integer	✅	Amount in minor units (kobo, cents, etc.)
source_amount.currency	string	✅	Currency code (ISO 4217)
total_fees	object	✅	Total fees charged
total_fees.value	integer	✅	Fee amount in minor units
total_fees.currency	string	✅	Currency code of the fee
destination_amount	object	✅	Amount bought
destination_amount.value	integer	✅	Amount in minor units
destination_amount.currency	string	✅	Currency code
destination	object	✅	Destination details
destination.type	string	✅	Type of destination ("account" or "fx_settlement_batch")
destination.id	string (UUID)	✅	ID of the destination
quote_id	string (UUID)	❌	ID of the quote used to generate this conversion
fx	object	✅	Foreign exchange rate details
fx.pair	string	✅	Currency pair in format "base/quote"
fx.base_currency	string	✅	Source currency
fx.quote_currency	string	✅	Destination currency
fx.rate	number	✅	Exchange rate applied
description	string	✅	Description of the exchange
balance_before	object	✅	Account balance before conversion
balance_before.value	integer	✅	Balance amount in minor units before the conversion
balance_before.currency	string	✅	Currency code of the balance
balance_after	object	✅	Account balance after conversion
balance_after.value	integer	✅	Balance amount in minor units after the conversion
balance_after.currency	string	✅	Currency code of the balance

FX Object

The fx object provides detailed information about the foreign exchange rate used in a conversion transaction. It specifies how currencies are valued relative to each other and helps interpret the conversion operation correctly.

Property	Type	Required	Description
pair	string	✅	Currency pair notation showing the exchange relationship in format "base/quote" (e.g., "NGN/USD")
base_currency	string	✅	The source currency code in the exchange rate pair (the currency being sold). This is the currency of the source account
quote_currency	string	✅	The target currency code in the exchange rate pair (the currency being bought or exchanged into)
rate	number	✅	Exchange rate applied to the conversion. How many units of the `base_currency` equal 1 unit of the `quote_currency`.

Understanding Exchange Rates

Rate Interpretation

The rate in the FX object represents how many units of the base_currency equal 1 unit of the quote_currency.

For example, if:

base_currency is "NGN"
quote_currency is "USD"
rate is 1765

This means: 1765 NGN is sold to get 1 USD

Important Note on Precision

The system handles these conversions internally, but it's important to understand that:

All amounts in API requests and responses are in minor currency units
The precision of the rate can get up to 10 decimals
The exchange rate is expressed in major currency units
Rounding may occur during conversion, especially when involving currencies with different precision requirements

Currency Pair Notation

The pair property follows the standard foreign exchange notation where:

The first currency is the base_currency (the currency you're selling)
The second currency is the quote_currency (the currency you're buying)
They are separated by a forward slash (e.g., "NGN/USD")

Example FX Object

{
  "pair": "NGN/USD",
  "base_currency": "NGN",
  "quote_currency": "USD",
  "rate": 1765
}

Example Object

{
    "data": {
        "id": "0196b0ff-5102-7f43-8546-8a3adf164e9f",
        "state": "PENDING",
        "status_description": "Conversion waiting to be processed",
        "created_date": "2025-05-08T17:44:04.610Z",
        "updated_date": "2025-05-08T17:44:04.821Z",
        "internal_reference": "wz-exchange-tW3x-1746726244610",
        "client_metadata": {},
        "account_id": "01961ef1-b21c-79ea-a3f3-4764c3b988ba",
        "source_amount": {
            "value": 10000000,
            "currency": "NGN"
        },
        "total_fees": {
            "value": 0,
            "currency": "NGN"
        },
        "destination_amount": {
            "value": 5666,
            "currency": "USD"
        },
        "destination": {
            "type": "account",
            "id": "01961ef1-b21d-718f-8f06-9da328e8361e"
        },
        "balance_before": {
            "value": 1962990243,
            "currency": "NGN"
        },
        "balance_after": {
            "value": 1952990243,
            "currency": "NGN"
        },
        "fx": {
            "pair": "NGN/USD",
            "rate": 1765,
            "base_currency": "NGN",
            "quote_currency": "USD"
        },
        "description": "Currency exchange from NGN to USD"
    }
}