Currency Conversion API

Initiate Currency Conversion

Before initiating a conversion, you need to first get the exchange rate for the currency pair you want to convert. Once you have the exchange rate for the currency pair, you can start the conversion by making a POST request to the Initiate Currency Conversion endpoint;

{{baseurl}}/api/v1/conversions/

The request body should have the following parameters:

Field	Data Type	Description
`rate_reference`	String	A string to reference the rate that was gotten for the amount.
`amount`	Number	The amount to be converted.
`from_currency`	String	The currency from which the user is converting. For example, if you wanted to convert Nigerian Naira to US Dollar, the `from_currency` will be NGN.
`to_currency`	String	The currency to which the user wants to convert funds. For example, if you wanted to convert Nigerian Naira to US Dollar, the `to_currency` will be USD.
`customer_name`	String	The name of customer initiating the conversion.
`customer_email`	String	The email of the customer initiating the conversion.
`narration`	String	The description of the transaction.

Here's an example of a response to the request:

{
  "status": true,
  "message": "Conversion processed successfully",
  "data": {
    "converted_amount": "14400.00",
    "source_amount": "10.00",
    "destination_currency": "NGN",
    "exchange_rate": "1440.00",
    "reference": "1ccdb7da-e732-4610-a17f-5abfb7617d90",
    "source_currency": "USD",
    "status": "success"
  }
}

An email notification will also be sent to you immediately the currency conversion is completed.

🚧
Always ensure that you have sufficient funds in your available balance for the currency you want to convert from.

Retrieving Currency Conversion Transaction

You can retrieve a conversion transaction to get the status and the details of that transaction using its reference.

To do this, make a GET request to the Retrieve Conversion Transaction endpoint;

{{baseurl}}/api/v1/conversions/:reference

The request should have the following parameters:

Field	Data Type	Description
`reference`	String	Required - the reference of the transaction.

Here's an example of the response to the request to retrieve a conversion transaction:

{
  "status": true,
  "code": "AA000",
  "message": "Conversion retrieved successfully",
  "data": {
    "source_currency": "NGN",
    "destination_currency": "USD",
    "exchange_rate": "1870.00",
    "source_amount": "4000.00",
    "converted_amount": "2.14",
    "status": "success",
    "reference": "2ccdb7da-e732-4610-a17f-5abfb7617d90",
    "channel": "api",
    "customer_name": "John",
    "customer_email": "[email protected]",
    "narration": "sample narration",
    "transaction_date": "2025-02-26 13:36:57"
  }
}

Fetching Conversion Transaction History

You can retrieve the history of your currency conversion transactions within a given period using the Conversion History endpoint.

To do this, make a GET request to the Conversion history endpoint with the desired period;

{{baseurl}}/api/v1/conversions

The request body should have the following parameters:

Field	Data Type	Description
`date`	String	Required- The specific date or date range (start date and end date)
`limit`	String	Required- The number of logs to return (Default value: `20` ,Maximum Value: `100`)
`page`	String	Required- The page number of the requested page (Default value: `1`)

Here's an example of a response to the request to fetch conversions history:

{
  "status": true,
  "message": "Conversion transactions retrieved successfully",
  "data": {
    "history": [
      {
        "source_currency": "NGN",
        "destination_currency": "USD",
        "exchange_rate": "1870.00",
        "source_amount": "4000.00",
        "converted_amount": "2.14",
        "status": "success",
        "reference": "2ccdb7da-e732-4610-a17f-5abfb7617d90",
        "channel": "api",
        "customer_name": "John",
        "customer_email": "[email protected]",
        "narration": "sample narration",
        "transaction_date": "2025-02-26 13:36:57",
        "account": {
          "name": "Demo Merchant",
          "email": "[email protected]"
        }
      },
      {
        "source_currency": "USD",
        "destination_currency": "NGN",
        "exchange_rate": "1440.00",
        "source_amount": "10.00",
        "converted_amount": "14400.00",
        "status": "success",
        "reference": "1ccdb7da-e732-4610-a17f-5abfb7617d90",
        "channel": "api",
        "customer_name": "John",
        "customer_email": "[email protected]",
        "narration": "sample narration",
        "transaction_date": "2025-02-26 13:33:20",
        "account": {
          "name": "Demo Merchant",
          "email": "[email protected]"
        }
      }
    ]
  }
}