Integration Notes

Before integration starts, make sure the platform has issued your merchant ID, API key, and API domain. The content below is the merchant API integration guide.

Request Rules

• GET endpoints accept query parameters.
• POST endpoints accept JSON bodies only. Non-JSON requests are rejected.
• All merchant endpoints return JSON.
• Keep the response rid when troubleshooting with the platform.

Security Checks

Every request is verified in this order:

• required fields mch_id, timestamp, nonce, sign
• merchant existence and enabled status
• merchant API IP whitelist, if configured
• request signature

Common Parameters

These parameters are required on every merchant API request:

Parameter	Type	Required	Description
mch_id	integer	Yes	Merchant ID. Pass it as an integer
timestamp	integer	Yes	10-digit UNIX timestamp. Pass it as an integer
nonce	string	Yes	Random token, alphanumeric only. Length: 6-24
sign	string	Yes	MD5 signature, lower case

Response Format

Success:

{
  "code": 200,
  "payload": {
    "id": "C202605040001",
    "trans_id": "ORDER-10001"
  }
}

Failure:

{
  "code": 400,
  "rid": "4f25d940-6f6b-4f78-a5a5-4a2f4f0f90ab",
  "errors": {
    "message": "[4f25d940-6f6b-4f78-a5a5-4a2f4f0f90ab] signature verification failed"
  }
}

Business Codes

The API returns these business codes in the JSON body:

code	Meaning
200	Success
400	Invalid params, signature error, or business validation failure
401	Unauthenticated
403	Forbidden
404	Route or resource not found
406	Request not acceptable, such as lock acquisition failure
429	Rate limited
503	Service unavailable or under maintenance

Note

The HTTP status code is not always the same as the JSON code. Use the JSON body as the source of truth and keep the rid for support.

Signature Algorithm

Use MD5 for the current integration. RSA is not available at the moment.

How To Sign

1. Take all request parameters except sign.
2. Remove empty values.
3. Sort by parameter name in ASCII order.
4. Join them as key=value&key2=value2.
5. Prefix the string with the API key and &, producing md5_key&key=value...
6. Generate the MD5 digest of the final string and send it as sign.

Example payload:

{
  "mch_id": 10001,
  "trans_id": "ORDER-10001",
  "amount": "100.00",
  "channel": "bank",
  "callback_url": "https://merchant.example.com/callback/collect",
  "nonce": "ABC123XYZ",
  "timestamp": 1714819200
}

If the API key is demo_key_123456, the signing source string is:

demo_key_123456&amount=100.00&callback_url=https://merchant.example.com/callback/collect&channel=bank&mch_id=10001&nonce=ABC123XYZ&timestamp=1714819200&trans_id=ORDER-10001

Apply MD5 to that string to get sign.

RSA Signature

Not available at the moment.

Integration Tips

• Set Content-Type: application/json explicitly on POST requests
• Your callback endpoint must return plain text success
• The collect and payout query APIs have different response formats; see the endpoint details
• Insufficient channel permission: xxx means the merchant has not been granted that channel