Overview

The Conversions API allows you to convert funds between different currencies. You can create conversions directly or by using a previously generated quote. This guide explains how to use the API to create currency conversions.

Endpoint

POST banking/v2/conversions

Authentication

Requires a valid API key provided in the header: x-waza-api-key. Certain institutions may also require OTP verification.

Request Body

You can create a conversion using two different methods:

1. Direct Conversion: Providing all conversion details including source account, amount, and destination
2. Quote-based Conversion: Using a previously generated quote ID

The request body takes a different structure depending on which method you choose.

Direct Conversion

For direct conversions, use the following structure:

Quote-based Conversion

For conversions based on a previously generated quote, use this structure:

Destination Types

Account Destination

Use this to convert directly into another account:

Response

A successful request returns an HTTP 200 status code and a Conversion object.

Examples

Example 1: Direct Conversion to Another Account

{
  "instruction": "direct",
  "amount": 10000000,
  "source_account_id": "01961ef1-b21c-79ea-a3f3-4764c3b988ba",
  "destination": {
    "type": "account",
    "account_id": "01961ef1-b21d-718f-8f06-9da328e8361e"
  },
  "fixed_side": "source",
  "description": "Currency exchange from NGN to USD",
  "client_reference": "CLIENT-FX-20230514-001",
  "client_metadata": {
    "purpose": "vendor_payment"
  }
}

Example 2: Conversion from Quote

{
  "instruction": "quote",
  "quote_id": "32165498-7654-3210-fedc-ba9876543210",
  "description": "NGN to USD conversion using locked rate",
  "client_reference": "CLIENT-FX-QUOTE-20230516-003",
  "client_metadata": {
    "department": "finance",
    "purpose": "operating_expenses"
  }
}

Fixed Side in Currency Conversions

The "fixed side" parameter is a key concept in currency conversions that determines which amount remains constant during the exchange operation. When converting between currencies, you can either specify an exact amount to send (source fixed) or an exact amount to receive (destination fixed).

How Fixed Side Works in Conversions

Source Fixed (Default)

When fixed_side is set to source or omitted:

• The exact specified amount will be debited from your source account
• The system applies the exchange rate to calculate the destination amount
• The destination account receives the calculated amount in the target currency
• Useful when you have a specific amount you want to convert

For example, if you set amount: 10000000 (100,000 in NGN) with fixed_side: "source", exactly 100,000 NGN will be debited, and the equivalent amount in the destination currency (e.g., USD) will be credited based on the current exchange rate.

Destination Fixed

When fixed_side is set to destination:

• The exact specified amount will be credited to the destination account
• The system calculates how much to debit from your source account based on the exchange rate
• Your source account is debited with the calculated amount (plus any fees)
• Useful when you need to receive a specific amount in the target currency

For example, if you set amount: 5000 (50 USD) with fixed_side: "destination", the system will calculate how much NGN needs to be debited to ensure the destination account receives exactly 50 USD.

Implementation in Conversion API Requests

Direct Conversion with Source Fixed

{
  "instruction": "direct",
  "amount": 10000000,  // 100,000 in minor units (e.g., NGN kobo)
  "source_account_id": "01961ef1-b21c-79ea-a3f3-4764c3b988ba",
  "destination": {
    "type": "account",
    "account_id": "01961ef1-b21d-718f-8f06-9da328e8361e"
  },
  "fixed_side": "source",  // Or omit for the same behavior
  "description": "Converting a fixed amount of NGN to USD"
}

In this example, exactly 100,000 NGN will be debited from your account, and the destination account will receive the calculated USD equivalent based on the current exchange rate.

Direct Conversion with Destination Fixed

{
  "instruction": "direct",
  "amount": 5000,  // 50 in minor units (e.g., USD cents)
  "source_account_id": "01961ef1-b21c-79ea-a3f3-4764c3b988ba",
  "destination": {
    "type": "account",
    "account_id": "01961ef1-b21d-718f-8f06-9da328e8361e"
  },
  "fixed_side": "destination",
  "description": "Ensuring exactly 50 USD is received"
}

In this example, the system will calculate how much NGN to debit from your account to ensure the destination account receives exactly 50 USD.

Important Considerations for Conversions

1. Default Behavior: If fixed_side is not specified, the system defaults to source as the fixed side.

2. Amount Interpretation:

   • With fixed_side: "source", the amount is how much will be debited from the source account
   • With fixed_side: "destination", the amount is how much will be credited to the destination account

3. Currency Precision:

   • Different currencies have different precision (decimal places)
   • All amounts are specified in minor units (kobo, cents) in the API
   • Be aware that rounding might occur during conversion, especially with exotic currency pairs

4. Exchange Rate Application:

   • The exchange rate is applied differently depending on the fixed side
   • Source fixed: Destination amount = Source amount ÷ Exchange rate
   • Destination fixed: Source amount = Destination amount × Exchange rate

5. Conversion Limits:

   • There may be minimum and maximum conversion amounts depending on the currencies involved
   • When using destination fixed, ensure the calculated source amount falls within allowable limits

Example Conversion Scenarios

Scenario 1: Converting a specific amount

A business wants to convert exactly 500,000 NGN to USD:

• Uses fixed_side: "source" and amount: 50000000 (in kobo)
• The USD account receives the equivalent based on the current exchange rate
• The business knows exactly how much NGN will be converted

Scenario 2: Funding an account with a specific amount

A business needs to fund a USD account with exactly 2,500 USD from their NGN account:

• Uses fixed_side: "destination" and amount: 250000 (in cents)
• The system calculates how much NGN to convert
• The USD account receives exactly 2,500 USD regardless of exchange rate fluctuations

Quote-Based Conversions and Fixed Side

When generating a quote for a conversion, you can also specify the fixed side:

{
  "source_account_id": "01961ef1-b21c-79ea-a3f3-4764c3b988ba",
  "amount": 10000000,
  "fixed_side": "source",
  "destination": {
    "type": "account",
    "account_id": "01961ef1-b21d-718f-8f06-9da328e8361e"
  }
}

The quote will lock in the exchange rate for a specific period. When you later execute the conversion using the quote ID, the system honors the fixed side specified when the quote was generated:

{
  "instruction": "quote",
  "quote_id": "32165498-7654-3210-fedc-ba9876543210",
  "description": "Conversion using locked rate"
}

Using quotes is particularly valuable when you want to guarantee either the source amount debited or the destination amount credited, regardless of rate fluctuations between quote generation and conversion execution.

By understanding and properly using the fixed side parameter, you can ensure your currency conversions meet your specific business needs, whether you're working with a fixed budget or need to ensure a specific amount is received.

Sample CURL Requests

Creating a Direct Conversion

curl -X POST "https://api.waza.co/banking/v2/conversions" \
  -H "x-waza-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "direct",
    "amount": 10000000,
    "source_account_id": "01961ef1-b21c-79ea-a3f3-4764c3b988ba",
    "destination": {
      "type": "account",
      "account_id": "01961ef1-b21d-718f-8f06-9da328e8361e"
    },
    "description": "Currency exchange from NGN to USD",
    "client_reference": "CLIENT-FX-20230514-001"
  }'

Creating a Conversion from Quote

curl -X POST "https://api.waza.co/banking/v2/conversions" \
  -H "x-waza-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "quote",
    "quote_id": "32165498-7654-3210-fedc-ba9876543210",
    "description": "NGN to USD conversion using locked rate",
    "client_reference": "CLIENT-FX-QUOTE-20230516-003"
  }'