Create Quote Example - NGN to CNY

This example demonstrates a quote request for converting 5,000 NGN (Nigerian Naira) to CNY (Chinese Yuan). 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:

ALIPAY: For recipients identified by email or mobile.
WECHAT: For recipients identified by mobile only.
BANK_TRANSFER: For transfers to both individual and business accounts in China.

Endpoint

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

Authentication

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

Your JSON request body should specify the source and target details, and optionally the intended payment channel.

{
  "paymentChannel": "string", // Optional: ALIPAY, WECHAT, BANK_TRANSFER
  "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 WeChat as payment channel:

curl --location --request POST '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"
    }
}'

To use other payment channels, simply replace WECHAT with either ALIPAY or BANK_TRANSFER

Sample Response (200 OK)

response.json

{
    "message": "quote successfully created",
    "status": "success",
    "data": {
        "id": "387ea2fc-564e-45c2-bcf9-6abc30127b7f",
        "source": {
            "currency": "NGN",
            "country": "NG",
            "amount": 5000
        },
        "target": {
            "currency": "CNY",
            "country": "CN",
            "amount": 24.04
        },
        "rate": 208.02,
        "fee": {
            "amount": 20
        },
        "rules": [
            {
                "category": "LIMIT",
                "appliedCurrency": "CNY",
                "appliedCountry": "CN",
                "transaction": {
                    "minimum": 10,
                    "maximum": 70,000
                },
                "invoice": 70000
            }
        ],
        "summary": {
            "total": 5020
        }
    }
}

ℹ️

Note: Our processing fee is dynamic.

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 (5000 NGN)

Target (Receiving) Details

Field	Type	Description
`target.currency`	String	Target currency (CNY)
`target.country`	String	Destination country (CN)
`target.amount`	Number	Converted amount (24.04 CNY)

Exchange Rate and Fees

Field	Type	Description
`rate`	Number	Exchange rate applied (208.02)
`fee.amount`	Number	Transaction fee (20 NGN)

Transaction Rules

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

Summary

Field	Type	Description
`summary.total`	Number	Total amount user pays (5020 NGN)

Key Takeaways

The user sends 5,000 NGN, which is converted to 24.04 CNY at an exchange rate of 208.02.
A transaction fee of 20 NGN is applied.
The total amount the user must pay (including fees) is 20 NGN.
A transaction limit rule restricts transactions between 10 CNY and 70,000 CNY.

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.

NGN - NGN Example NGN - USD Example