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
• selected API key ownership, enabled status, and endpoint capability
• 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
api_key_id	string	No	API key ID (26-character ULID). Required when using a non-default API key and included in the signature

API Key Selection

• When api_key_id is omitted, the platform uses the merchant's default API key for signature verification and capability checks. This keeps existing integrations compatible.
• When using a non-default API key created in the console, send its api_key_id and sign the request with that key's secret.
• The API key must be enabled and granted the capability required by the endpoint; otherwise the request is rejected.

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

Whether an API call succeeds is determined solely by code. code=200 means the API call succeeded; any other code value indicates an API call error. When an API call fails, use the code in the response body as the source of truth, see what happened from errors.message field and record the rid.

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. If api_key_id is sent, it must remain in the signing parameters.
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,
  "api_key_id": "01M0D4WJWZZYVH26943FP99ZV8",
  "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&api_key_id=01M0D4WJWZZYVH26943FP99ZV8&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