Create Quote API

The Create Quote API allows users to generate a quote for a specified source and destination currency. This quote locks in the exchange rate, fees, and amounts for a short period, which you can then use to initiate a payout transaction.

This endpoint creates a currency exchange quote for a user, considering applicable business rules. The response includes the converted amount, exchange rate, fees, and transaction limits.

Endpoint

POST {{baseURL}}/v1/quote

Request Headers

Header	Description	Required	Example Value
`x-api-key`	API key for authentication	✅ Yes	`YOUR_API_KEY`
`Content-Type`	Request content type	✅ Yes	`application/json`

Request & Response Examples

This example demonstrates converting 100,000 NGN to EUR.

cURL Request

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

Successful Response (200 OK)

{
  "message": "quote successfully created",
  "status": "success",
  "data": {
    "id": "74bgf9ea-141e-13c7-ade9-xxxxxxxxxxxxx",
    "source": { "currency": "NGN", "country": "NG", "amount": 100000 },
    "target": { "currency": "EUR", "country": "DK", "amount": 61.72 },
    "rate": 1620.21,
    "fee": { "amount": 1000 },
    "rules": [
      {
        "category": "LIMIT",
        "appliedCurrency": "EUR",
        "appliedCountry": "DK",
        "transaction": { "minimum": 10, "maximum": 25000 },
        "invoice": 25000
      }
    ],
    "summary": { "total": 101000 }
  }
}

General Response Breakdown

ℹ️

Note: Every quote expires 10 minutes after it has been created.

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
`source.country`	String	Country where the transaction originates
`source.amount`	Number	Amount to be converted

Target (Receiving) Details

Field	Type	Description
`target.currency`	String	Target currency
`target.country`	String	Destination country
`target.amount`	Number	Converted amount

Exchange Rate and Fees

Field	Type	Description
`rate`	Number	Exchange rate applied
`fee.amount`	Number	Transaction fee

Transaction Rules

Field	Type	Description
`rules[].category`	String	Type of rule applied (e.g., LIMIT)
`rules[].appliedCurrency`	String	Currency the rule applies to
`rules[].appliedCountry`	String	Country the rule applies to
`rules[].transaction.minimum`	Number	Minimum allowed transaction
`rules[].transaction.maximum`	Number	Maximum allowed transaction
`rules[].invoice`	Number	Maximum invoice amount

Summary & Expiration

Field	Type	Description
`summary.total`	Number	Total amount user pays (source amount + fee)
`expiresInSeconds`	Number	Quote expiration time in seconds

Error Handling

Status Code	Meaning	Example Response	How to Handle
400	Bad Request	`Required field missing or invalid request`	Check API documentation for required fields and input formats.
401	Unauthorized	`Invalid authentication credentials`	Verify API key in the header is correct and active.
403	Forbidden	`Your IP address is not allowed to access this service`	Whitelist your IP address in the API Management settings.
429	Too Many Requests	`API rate limit exceed`	Implement retry with exponential backoff.
500	Internal Server Error	`An unexpected error occurred on the server`	Retry after some time; if persistent, contact support.

Best Practices

✅ Always include a valid x-api-key in the request header.
✅ Ensure that the source and target country and currency codes are valid to prevent request failures.
✅ Handle transaction limits appropriately by inspecting the rules object in the response.
✅ Save the data.id from the quote response, as it will be required to execute the payout.

Get Quote How Payouts works in meCash