Skip to main content
Use this endpoint to generate a guaranteed exchange rate for a specific corridor. The quote response includes a quoteId that you must supply when you create the payout.

​
Endpoint

POST {{baseURL}}/v1/quote
Quotes expire after the duration returned in expiresInSeconds. Create the payout before it expires or request a fresh quote.

​
Request body

copy
{
  "paymentChannel": "BANK_TRANSFER",
  "source": {
    "amount": 150000,
    "country": "NG",
    "currency": "NGN"
  },
  "target": {
    "country": "US",
    "currency": "USD"
  }
}

​
Body fields

FieldTypeDescriptionRequiredExample
paymentChannelStringPayment channel used to settle the payout (e.g. BANK_TRANSFER, MOBILE_MONEY).✅ YesBANK_TRANSFER
source.amountNumberAmount you want to convert in the source currency.✅ Yes150000
source.countryStringISO 3166-1 alpha-2 code for the sender country.✅ YesNG
source.currencyStringISO 4217 code for the sender currency.✅ YesNGN
target.countryStringISO 3166-1 alpha-2 code for the recipient country.✅ YesUS
target.currencyStringISO 4217 code for the recipient currency.✅ YesUSD

​
Request headers

HeaderTypeDescriptionRequiredExample
x-api-keyStringAPI key associated with your workspace.✅ YesYOUR_API_KEY
Content-TypeStringMedia type of the request body.✅ Yesapplication/json

​
Request examples

curl --request POST '{{baseURL}}/v1/quote' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentChannel": "BANK_TRANSFER",
    "source": {
      "amount": 150000,
      "country": "NG",
      "currency": "NGN"
    },
    "target": {
      "country": "US",
      "currency": "USD"
    }
  }'

​
Successful response

copy
{
  "message": "quote successfully created",
  "status": "success",
  "data": {
    "id": "e5eec724-38f9-40e2-9i86-xxxxxxxxxxxxx",
    "source": {
      "currency": "NGN",
      "country": "NG",
      "amount": 150000
    },
    "target": {
      "currency": "USD",
      "country": "US",
      "amount": 81.97
    },
    "rate": 1830,
    "fee": {
      "amount": 0
    },
    "summary": {
      "total": 150000
    },
    "rules": [
      {
        "category": "LIMIT",
        "appliedCurrency": "USD",
        "transaction": {
          "minimum": 1,
          "maximum": 200000
        }
      }
    ],
    "expiresInSeconds": 600,
    "settlementTime": "1 hr"
  }
}

​
Field reference

FieldTypeDescription
idStringQuote identifier to reuse in payout requests.
rateNumberExchange rate applied to the conversion.
summary.totalNumberAmount to debit in the source currency.
fee.amountNumberTotal fees charged for the quote.
expiresInSecondsNumberTime remaining before the quote becomes invalid.
rulesArrayCorridor rules that were evaluated (limits, compliance, etc.).

​
Error responses

StatusMessageCauseHow to handle
400Invalid country or currency ISO codeThe source/target country or currency combination is not supported.Use valid ISO codes for corridors enabled on your workspace.
400Invalid Payment Channel, check docs or contact supportpaymentChannel is not valid for the selected corridor.Choose a supported channel for the corridor and amount.
400Required field missing or invalid requestMandatory fields are missing or have invalid formats.Validate source, target, paymentChannel, and metadata before sending.
400Minimum target amount for transaction is {minimum_transaction_amount}Requested target amount is below the corridor’s minimum.Increase the target amount to at least the stated minimum.
400Maximum target amount for transaction is {maximum_transaction_amount}Requested target amount exceeds the corridor’s limit.Reduce the target amount below the maximum threshold.
400Transaction target amount {transaction_amount} requires invoiceAmount surpasses invoice thresholds that require documentation.Collect and attach the required invoice before retrying.
401API key missing or incorrectx-api-key header missing, invalid, or expired.Include the correct API key for sandbox/production.
403Quote route not available, contact supportEndpoint disabled for your workspace or environment.Reach out to support to enable quotes for the corridor.
403Access denied: IP address not whitelistedRequest originated from an IP that isn’t on your allowlist.Add your server IP in the dashboard.
429API rate limit exceededToo many quote requests in a short window.Apply exponential backoff and distribute requests.
500Service temporarily unavailableTemporary outage or maintenance event.Retry after a delay; contact support if persistent.

​
Best practices

  • Cache quotes temporarily so the user can confirm without re-requesting.
  • Surface the quote expiry countdown in your UI to encourage timely confirmation.
  • Use the Get Quote API if you need to display the quote again before payout.