Create Quote Example - NGN to USD
This example demonstrates a quote request for converting 100,000 NGN (Naira) to USD (United States Dollar. This quote locks in the exchange rate, fees, and amounts for a short period, which you can then use to initiate a payout transaction.
Supported Payment Channels
Quotes are often generated with a specific payout method in mind, as fees or limits might vary. This API supports getting quotes for payouts via:
- BANK_TRANSFER: For standard bank transfers.
Endpoint
POST {{baseURL}}/v1/quote
Header
Include these headers in your request:
| Header | Description | Required | Example Value |
|---|---|---|---|
x-api-key | API key for authentication | ✅ Yes | YOUR_API_KEY |
Content-Type | Request content type | ✅ Yes | application/json |
Remember to replace YOUR_API_KEY with your actual API key (Production or Sandbox).
Request Body
{
"paymentChannel": "string", //
"source": {
"amount": number,
"country": "string", // ISO 3166-1 alpha-2 code
"currency": "string" // ISO 4217 currency code
},
"target": {
"country": "string", // ISO 3166-1 alpha-2 code
"currency": "string" // ISO 4217 currency code
}
}Request Example with BANK_TRANSFER as payment channel:
curl --location --request POST '{{baseURL}}/v1/quote' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"paymentChannel": "BANK_TRANSFER",
"source": {
"amount": 500000,
"country": "NG",
"currency": "NGN"
},
"target": {
"country": "US",
"currency": "USD"
}
}'Sample Response (200 OK)
{
"message": "quote successfully created",
"status": "success",
"data": {
"id": "98agb1da-351e-54b7-cde9-xxxxxxxxxxxxx",
"source": {
"currency": "NGN",
"country": "NG",
"amount": 500000
},
"target": {
"currency": "USD",
"country": "US",
"amount": 335.50
},
"rate": 1490.31,
"fee": {
"amount": 5000
},
"rules": [
{
"category": "LIMIT",
"appliedCurrency": "USD",
"appliedCountry": "US",
"transaction": {
"minimum": 20,
"maximum": 10000
},
"invoice": 10000
}
],
"summary": {
"total": 505000
}
}
}Response Breakdown
General Information
| Field | Type | Description |
|---|---|---|
message | String | Confirmation message |
status | String | Indicates success or failure |
data.id | String | Unique identifier for the quote |
Source (Sending) Details
| Field | Type | Description |
|---|---|---|
source.currency | String | Currency being exchanged (NGN) |
source.country | String | Country where the transaction originates (NG) |
source.amount | Number | Amount to be converted (500,000 NGN) |
Target (Receiving) Details
| Field | Type | Description |
|---|---|---|
target.currency | String | Target currency (USD) |
target.country | String | Destination country (US) |
target.amount | Number | Converted amount (335.50 USD) |
Exchange Rate and Fees
| Field | Type | Description |
|---|---|---|
rate | Number | Exchange rate applied (1490.31) |
fee.amount | Number | Transaction fee (5,000 NGN) |
Transaction Rules
| Field | Type | Description |
|---|---|---|
rules[].category | String | Type of rule applied (LIMIT) |
rules[].appliedCurrency | String | Currency the rule applies to (USD) |
rules[].appliedCountry | String | Country the rule applies to (US) |
rules[].transaction.minimum | Number | Minimum allowed transaction (20 USD) |
rules[].transaction.maximum | Number | Maximum allowed transaction (10,000 USD) |
rules[].invoice | Number | Maximum invoice amount (10,000 USD) |
Summary
| Field | Type | Description |
|---|---|---|
summary.total | Number | Total amount user pays (505,000 NGN) |
Key Takeaways
- The user sends 500,000 NGN, which is converted to 335.50 USD at an exchange rate of 1490.31.
- A transaction fee of 5,000 NGN is applied.
- The total amount the user must pay (including fees) is 505,000 NGN.
- A transaction limit rule restricts transactions between 20 USD and 10,000 USD.
Best Practices
- ✅ Include a valid API key (
x-api-key) in the request headers to authenticate the request. - ✅ Ensure that the source and target country and currency codes are valid to prevent request failures.
- ✅ Handle transaction limits appropriately to comply with API restrictions.