Create Quote API Documentation

The Quote API allows users to generate a quote for a specified source and destination currency. It calculates and returns data based on rules associated with the transaction.

Endpoint

POST: Create a 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.

URL: https://{{baseURL}}/v1/quote

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": "WECHAT",
   "source": {
        "amount": 5000,
        "country": "NG",
        "currency": "NGN"
    },
    "target": {
        "country": "CN",
        "currency": "CNY"
    }
}

Request Parameters

Field	Type	Description	Required	Example Value
paymentChannel	String	Payment method for the transaction	✅ Yes	"WECHAT" 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 --location --globoff 'https://{{baseURL}}/v1/quote' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
   "paymentChannel": "WECHAT",
   "source":{
        "amount": 5000,
        "country": "NG",
        "currency": "NGN"
    },
    "target":{
        "country": "CN",
        "currency": "CNY"
    }
}'

Try it out here!

Expected Responses

Success Response (200 OK)

If the request is successful, the API returns the following JSON response:

response.json

{
    "message": "quote successfully created",
    "status": "success",
    "data": {
        "id": "bb0a6d09-bf4c-45ef-b73b-6c378a672321",
        "source": {
            "currency": "NGN",
            "country": "NG",
            "amount": 5000.00
        },
        "target": {
            "currency": "CNY",
            "country": "CN",
            "amount": 22.77
        },
        "rate": 219.60300000,
        "fee": {
            "amount": 5.00
        },
        "rules": [
            {
                "category": "LIMIT",
                "appliedCurrency": "CNY",
                "appliedCountry": "CN",
                "transaction": {
                    "minimum": 10.00,
                    "maximum": 35000.00
                },
                "invoice": 35000.00
            }
        ],
        "summary": {
            "total": 5005.00
        }
    }
}

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.

Response Fields

Field	Type	Description
message	String	API response message
status	String	Success or failure status
data.quoteId	String	Unique identifier for the quote
data.rate	Number	Exchange rate applied
data.source.amount	Number	Source amount entered by user
data.source.currency	String	Source currency code
data.source.country	String	Source country code
data.target.amount	Number	Converted target amount
data.target.currency	String	Target currency code
data.target.country	String	Target country code
data.fee.amount	Number	Transaction fee applied
data.fee.currency	String	Currency of the transaction fee

ℹ️

Note: Quote expires 10 minutes after it has been created.

Error Handling

Status Code	Description	Example Response
400 Bad Request	Invalid request parameters	`{ "message": "Invalid input data" }`
401 Unauthorized	Missing or invalid API key	`{ "message": "Unauthorized access" }`
422 Unprocessable Entity	Business rule validation failed	`{ "message": "Invalid source or target currency" }`
500 Internal Server Error	Unexpected server issue	`{ "message": "An internal error occurred" }`

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