Error Code
TIP
Merchants need to sign API requests before sending them, and verify the signature field on async callback notifications after receiving them.
Order Result Rules
During integration, first confirm whether the request was accepted at the HTTP level, then read success, code, and data.orderStatus from the response body. Please note: code=00000 only means the request was accepted, not that the transaction succeeded; success only indicates whether the API call itself succeeded and should not be used alone as the final business result.
| Dimension | Purpose | Integration Guidance |
|---|---|---|
success | Indicates whether the API call itself succeeded | Use only as a supporting signal and always read it together with code |
code | Request acceptance result or failure reason | 00000 means the request was accepted; other values mean the request was not accepted or failed |
data.orderStatus | Order status | Returned only when transaction data exists; only terminal states should be used as the final business result |
Recommended Result Handling
code != 00000: the request was not accepted. Handle the error according to the error code and do not treat the order as successful.code = 00000anddata.orderStatus = PENDING: the order has been accepted but is still processing. This is a non-terminal state. Wait for the async callback or continue polling.code = 00000anddata.orderStatus ∈ {SUCCESS, PARTIAL SUCCESS, FAILED, EXPIRED, CANCELLED, REFUNDED}: the order is in a terminal state and can be handled as the final result.
Common Transaction orderStatus States
| Status | Meaning | Final State | Integration Guidance |
|---|---|---|---|
PENDING | Pending payment or processing | No | Do not treat it as the final result; wait for callback or continue polling |
SUCCESS | Transaction succeeded | Yes | Can be used as the final success result |
PARTIAL SUCCESS | Partially completed payment. The requested order amount and actual paid amount are different | Yes | Settle by the actual paid amount or handle the difference according to your business rules |
FAILED | Transaction failed | Yes | Can be used as the final failure result |
EXPIRED | Order expired | Yes | Can be used as the final failure result |
CANCELLED | User cancelled the order | Yes | Can be used as the final failure result |
REFUNDED | Refunded | Yes | Handle according to your refund flow |
Common Business code States
| Code | Description | Meaning | Integration Guidance |
|---|---|---|---|
| 00000 | Request accepted | The platform successfully accepted the request | Continue to determine the final result through data.orderStatus, async callback, or query APIs |
| 40001 | Invalid parameter format | Parameter format is incorrect or a required field is missing | Correct the request and resubmit |
| 40002 | Request expired | Timestamp is invalid or the request has expired | Sync server time and resubmit |
| 40003 | Insufficient balance | Account balance is insufficient | Top up or confirm balance before retrying |
| 40004 | Merchant status exception | Merchant account is abnormal | Contact your business or operations contact |
| 40101 | Invalid signature | Signature verification failed | Check the signing string, secret key, letter case, and empty-value filtering rules |
| 40102 | Unauthorized | API Key is invalid | Check whether the merchant access identifier is correct |
| 40301 | IP not allowed | IP address is not in the whitelist | Contact support to configure the whitelist |
| 40401 | Transaction not found | No transaction was found | If querying immediately after submission, wait 3-5 seconds and retry; if it still does not exist, verify the merchant order number |
| 40402 | Merchant not found | No merchant was found | Check whether the merchant configuration is correct |
| 40901 | Duplicate transaction | Transaction number already exists | Do not create another order with the same identifier; query the original order using the same merchantOrderNo |
| 50001 | Internal service error | Internal server error | Do not directly mark the order as failed; query the order first. For payout orders, contact support if the result remains unclear |
| 50002 | System error | System processing exception | Do not directly mark the order as failed; query the order first. For payout orders, contact support if the result remains unclear |