Create Quote API

The Create Quote API allows users to generate a quote for a specified source and destination currency.

Endpoint

POST : {{baseURL}}/v1/quote

Description

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.

Request Headers

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

Request Body

{
  "paymentChannel": " ",  // Payment method for the transaction
  "source": {
    "amount": ,          // Amount in the source currency
    "country": " ",           // Source country code (ISO 3166-1 alpha-2)
    "currency": " "          // Source currency code (ISO 4217)
  },
  "target": {
    "country": " ",           // Target country code (ISO 3166-1 alpha-2)
    "currency": " "          // Target currency code (ISO 4217)
  }
}

Request Parameters

Field	Type	Description	Required	Example Value
paymentChannel	String	Payment method for the transaction	✅ Yes	"BANK_TRANSFER" or "ALI_PAY"
source.amount	Number	Amount in the source currency	✅ Yes	5000
source.country	String	Source country code (ISO 3166-1 alpha-2)	✅ Yes	"NG"
source.currency	String	Source currency code (ISO 4217)	✅ Yes	"NGN"
target.country	String	Target country code	✅ Yes	"CN"
target.currency	String	Target currency code	✅ Yes	"CNY"

Example Request

cURL

curl --location --globoff '{{baseURL}}/v1/quote' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "paymentChannel": "",
  "source": {
    "amount": 150000,
    "country": "NG",
    "currency": "NGN"
  },
  "target": {
    "country": "CN",
    "currency": "CNY"
  }
}'

Responses

response.json

{
  "message": "quote successfully created",
  "status": "success",
  "data": {
    "id": "e5eec724-38f9-40e2-9i86-xxxxxxxxxxxxx",
    "source": {
      "currency": "NGN",
      "country": "NG",
      "amount": 150000.00
    },
    "target": {
      "currency": "CNY",
      "country": "CN",
      "amount": 81.97
    },
    "rate": 1830.00000000,
    "fee": {
      "amount": 0.00
    },
    "rules": [
      {
        "category": "LIMIT",
        "appliedCurrency": "CNY",
        "appliedCountry": "CN",
        "transaction": {
          "minimum": 1.00,
          "maximum": 20000000000000.00
        },
        "invoice": 200000000000.00
      }
    ],
    "summary": {
      "total": 150000.00
    },
    "expiresInSeconds": 600
  }
}

ℹ️

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

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
`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
`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

Field	Type	Description
`summary.total`	Number	Total amount user pays

Expiration

Field	Type	Description
`expiresInSeconds`	Number	Quote expiration time in seconds

Note:

Make sure to save the quote Id, it will be required for payouts
The exchange rate is dynamic and subject to change.
The fee and category parameters are preset in the meCash configuration.
Transaction limits (minimum/maximum amounts) are predefined in the system.

Error Handling

Status Code	Meaning	Example Response	How to Handle
400	Bad Request (No API Key)	No API key found in request	Ensure `x-api-key` header is sent with a valid key
400	Route Not Found	The Route is not supported	Contact support to get the correct route
400	Validation Error	Required field missing or invalid request	Check API documentation for required fields and input formats
401	Unauthorized (Invalid API Key)	Invalid authentication credentials	Verify API key in the header is correct and active in dashboard settings
403	Forbidden (Non-whitelisted IP)	Your IP address is not allowed to access this service	Whitelist your IP address in the API Management settings on the dashboard
422	Unprocessable Entity (Semantic Error)	Invalid value in request body	Review request body for semantic errors (e.g., invalid values or logic errors)
429	Too Many Requests (Rate Limited)	API rate limit exceed	Implement retry with exponential backoff; respect rate limits (e.g., 50 requests/sec)
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 values are valid.

How Quotes works in meCash Get Quote