Quote Generation

Before executing a foreign exchange transaction, you can use the Quotes API to obtain estimated costs, including exchange rates and applicable fees. Institutions can use this lock exchange using the generated quote IDs to ensure payments are processed at the locked rates.

Quote Generation Response

Available Quote Endpoints

The API offers two primary quote generation endpoints:

1. Exchange Quote (/banking/v2/quotes/conversions) - For direct currency conversion between accounts
2. Transfer Quote (/banking/v2/quotes/transfers) - For estimating transfer costs that involve different currencies

Exchange Quote API

The Exchange Quote API allows you to estimate the cost of converting funds from one currency to another between accounts.

Endpoint

POST /banking/v2/quotes/conversion

Authentication

All requests must include your API key in the header:

x-waza-api-key: YOUR_API_KEY

Request Parameters

Destination Types

When performing currency exchange operations, you must specify where the converted funds should go using the destination field. The system supports different destination types, each with specific requirements:

Account Destination

Used to transfer converted funds directly to a specific account.

"destination": {
  "type": "account",
  "account_id": "f8c3de45-1a23-40b7-9c12-bd567e4a9f01"
}

FX Settlement Batch Destination

Used to process converted funds through the FX settlement batching system for more efficient handling of multiple exchanges.

"destination": {
  "type": "fx_settlement_batch",
  "currency": "EUR"
}

Note: You must specify exactly one destination type in your request.

Example Request

curl --location 'https://api.sandbox.waza.co/lync/banking/v2/quotes/exchange' \
--header 'x-waza-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "amount": 1000000,
  "source_account_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "fixed_side": "source",
  "destination": {
    "type": "account",
    "account_id": "abcdef12-3456-7890-abcd-ef1234567890"
  }
}'

curl --location 'https://api.sandbox.waza.co/lync/banking/v2/quotes/exchange' \
--header 'x-waza-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "amount": 1000000,
  "source_account_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "fixed_side": "source",
  "destination": {
    "type": "fx_settlement_batch",
    "currency": "EUR"
  }
}'

Response

The response provides a comprehensive breakdown of the exchange operation, including amounts in both currencies and any applicable fees.

Example Response

{
  "id": "f3a8d962-e09b-42c1-b4b5-3f2e91239624",
  "sending_amount": {
    "value": 1000000,
    "currency": "USD"
  },
  "total_fees": {
    "value": 3500,
    "currency": "USD"
  },
  "billing_amount": {
    "value": 1003500,
    "currency": "USD"
  },
  "destination_amount": {
    "value": 920000,
    "currency": "EUR"
  },
  "fee_breakdown": [
    {
      "value": 2000,
      "currency": "USD",
      "description": "Conversion fee"
    },
    {
      "value": 1500,
      "currency": "USD",
      "description": "Settlement batch processing fee"
    }
  ],
  "expiry_date": "2023-07-15T14:30:00Z",
  "operation": "EXCHANGE",
  "rate": 0.92,
  "currency_pair": "USD/EUR",
  "source_account_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "destination": {
    "type": "Account",
    "id": "batch_eur_settlement_12345"
  }
}

Transfer Quote API

The Transfer Quote API allows you to estimate the cost of making a payment to a beneficiary in a different currency.

Endpoint

POST /banking/v2/quotes/transfers

Authentication

All requests must include your API key in the header:

x-waza-api-key: YOUR_API_KEY

Request Parameters

Example Request

curl --location 'https://api.sandbox.waza.co/lync/banking/v2/quotes/transfers' \
--header 'x-waza-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "source_account_id": "01961ef1-b21c-79ea-a3f3-4764c3b988ba",
    "amount": 100000000,
    "beneficiary_id": "019638b9-c63d-76c6-91f6-a7ccec3707ed"
}'

Response

The response provides a detailed breakdown of the transfer operation, including amounts, fees, and the effective exchange rate.

Example Response

{
    "data": {
        "sending_amount": {
            "value": 100000000,
            "currency": "NGN"
        },
        "total_fees": {
            "value": 150000,
            "currency": "NGN"
        },
        "billing_amount": {
            "value": 100150000,
            "currency": "NGN"
        },
        "destination_amount": {
            "value": 56657,
            "currency": "USD"
        },
        "fee_breakdown": [
            {
                "value": 150000,
                "currency": "NGN",
                "description": "Transfer Fees"
            }
        ],
        "expiry_date": "2025-04-17T09:21:21.491Z",
        "operation": "TRANSFER_WITH_EXCHANGE",
        "rate": 1765,
        "currency_pair": "NGN/USD",
        "source_account_id": "01961ef1-b21c-79ea-a3f3-4764c3b988ba",
        "destination": {
            "type": "Beneficiary",
            "id": "019638b9-c63d-76c6-91f6-a7ccec3707ed"
        }
    }
}

Understanding Fixed Side

The fixed_side parameter is crucial for FX quotes:

• fixed_side="source": The source amount is fixed, and the destination amount will be calculated based on the current exchange rate. Use this when you know how much you want to send.

• fixed_side="destination": The destination amount is fixed, and the source amount will be calculated. Use this when you need to ensure the recipient gets a specific amount.

Quote Expiration and Usage

All quotes have an expiration time, typically 15 minutes after creation. After a quote expires, you must generate a new one before proceeding.

To use a quote:

1. Generate a quote using the appropriate endpoint
2. Store the quote ID returned in the response
3. Reference this quote ID when creating the actual payment or exchange transaction
4. Execute the transaction before the quote expires

Currency Support

The API supports a range of currencies, including fiat currencies (USD, EUR, GBP, NGN, etc.) and stablecoins (USDT, USDC). For a complete list of supported currencies, you can use the /banking/v2/data/supported-currencies endpoint.

Error Handling

Common Error Codes

Error Response Example

{
    "error": {
        "message": "Unable to perform this operation",
        "code": "INTERNAL_SERVER_ERROR",
        "description": "Something went wrong",
        "context": {
            "request_id": "5f4306cf-c8d1-4623-ae3b-be2881394899"
        }
    }
}

Best Practices

1. Always generate a fresh quote before executing an FX transaction to ensure you have the most current rates.

2. Store the quote ID and use it to apply the agreed rate when executing the transaction.

3. Implement error handling to manage rate fluctuations and unsupported currency pairs gracefully.

4. Consider time zones when working with quote expiration times. All timestamps are in UTC.

5. Validate beneficiary details before requesting a transfer quote to ensure the payment can be processed successfully.

Need Help?

For additional assistance or to report issues with the FX Quote API, please contact our support team with your API key and any relevant quote ID or context.request_id.