API Reference

Introduction

This page covers merchant API responses and common error codes.

Unified response structure

Responses uniformly contain four top-level fields: success, code, data, and msg.

field	type	meaning
`success`	boolean	`true` indicates success; `false` indicates failure.
`code`	integer	`0` means success; any other value is an error code.
`data`	object \| array \| null	Response data.
`msg`	string	Error message.

Except for authentication failures, which return HTTP 401, all other failures return HTTP 200 with the failure indicated inside the response structure.

Example responses

Typical success response:

{
  "success": true,
  "code": 0,
  "data": {
    "orderId": "ORDER_10001"
  },
  "msg": "ok"
}

Typical business failure response:

{
  "success": false,
  "code": 2,
  "data": null,
  "msg": "parameter error"
}

Typical authentication failure response:

HTTP/1.1 401 Unauthorized

{
  "success": false,
  "code": 14,
  "data": null,
  "msg": "signature is invalid"
}

Error codes

code	name	default message	meaning
0	`OK`	`ok`	Request succeeded.
1	`UNKNOWN_ERROR`	`unknown error`	Unexpected internal failure.
2	`PARAMETER_ERROR`	`parameter error`	Request parameters are invalid, missing, or unsupported.
14	`TOKEN_INVALID`	`The token is invalid.`	API authentication failed because of missing headers, invalid timestamp, invalid signature, expired key, replayed request, or similar signing issues.
15	`MERCHANT_IS_BANNED`	`The merchant is banned.`	Merchant is unavailable.
18	`ORDER_PAY_EXPIRED`	`The order payment has expired.`	Order has expired.
19	`RATE_LIMITED`	`too many requests`	Request rate limit exceeded.
24	`MERCHANT_NOT_ACTIVE`	`merchant is not active, please recharge`	Merchant is not active; please top up the processing fee balance.

Integration recommendations

Always inspect the JSON body, not only the HTTP status code.
Treat code = 0 as the success condition for business logic.
Keep merchant order IDs unique and stable so retries remain idempotent.
For request signing, refer to Authentication.