Collection API compat1 (legacy protocol)

For merchants already integrated with the old system's collection API: merchant ID, key, signature, parameters and responses are all unchanged. Only the gateway address changes to this platform's https://api.xx2system.xyz. Merchants opened on this platform (merchant ID starting with M) use it too, sending the merchant ID as is.

Common rules #

• Any method works (GET or POST); parameters may be in a form body or in the query string; if a name repeats, the last value wins.
• You may also put all parameters into one JSON string in the single parameter params (all other loose parameters are then ignored).
• JSON bodies are not read: sending application/json is the same as sending no parameters.
• Values for create order and query order must not contain characters such as &, < or > (rejected as XSS). So notifyUrl can carry at most one query parameter of its own.
• Failures are HTTP 200 too; look at retCode: SUCCESS or FAIL, with the reason in retMsg.
• Optional common parameters: reqTime (yyyyMMddHHmmss; the difference from now is not checked) and version (must be 1.0).

Create order create_order #

Request parameters #

• The amount is in the currency's minor unit, digits only, greater than 0.
• mchOrderNo must be unique per merchant: a duplicate gets 该商户订单已存在[mchOrderNo=…] and the original order is not returned.
• Without param2 (payer name) the channel settings decide: either a fixed name is used, or the payer first enters a name on our page (see “Payer name page” below).

Successful response #

There are only two payMethod values:

• formJump: send the payer to payUrl; payParams holds the same address.
• cardInfo: the receiving card details (accountName, accountNo, bankName in payParams); there is no payUrl.

{"retCode":"SUCCESS","sign":"FC72E9A94FE742797A6939FD5975B5D0","payMethod":"formJump","payUrl":"https://cashier.example.com/pay/8a1b2c","payParams":{"payMethod":"formJump","payUrl":"https://cashier.example.com/pay/8a1b2c"}}

{"retCode":"SUCCESS","sign":"299712E3593CB68C0AFF5901493FF777","payMethod":"cardInfo","payParams":{"accountName":"张三","accountNo":"6222021234567890123","bankName":"中国工商银行"}}

When the response is signed, payParams is one value: its first-level keys are sorted and it is written as compact JSON (see Signatures).

Failure response #

{"retCode":"FAIL","retMsg":"暂无可用支付通道,请稍后重试"}

• Most failures carry no sign; only failures returned normally by a channel are signed.
• Common failure texts are listed under Error codes.

Payer name page #

When the channel needs the payer's name and you did not send param2, the successful response is a formJump whose payUrl points to this platform's name page https://api.xx2system.xyz/api/pay/input_name?t=…. The payer enters a name there and then goes on to the payment page or sees the card details. The page is in Chinese only. Handle it like any other redirect; no code change is needed.

Example #

mchId=20000001
productId=8001
mchOrderNo=ORDER20260918001
amount=10000
notifyUrl=https://merchant.example.com/notify
subject=goods
body=goods
param1=shop-7
param2=张三
reqTime=20260918120000

amount=10000&body=goods&mchId=20000001&mchOrderNo=ORDER20260918001&notifyUrl=https://merchant.example.com/notify&param1=shop-7&param2=张三&productId=8001&reqTime=20260918120000&subject=goods&key=demo-key-NOT-REAL-do-not-use-0001

86032564C62F16F220F9DBAD7D88C690

mchId=20000001&productId=8001&mchOrderNo=ORDER20260918001&amount=10000&notifyUrl=https%3A%2F%2Fmerchant.example.com%2Fnotify&subject=goods&body=goods&param1=shop-7&param2=%E5%BC%A0%E4%B8%89&reqTime=20260918120000&sign=86032564C62F16F220F9DBAD7D88C690

Query order query_order #

Request parameters #

• If payOrderId is given it is looked up first; if nothing is found it is tried again as your order number.
• executeNotify=true: if the order has succeeded, the callback is sent once more (only the string true, any case; 1 does not count).

Successful response #

These 14 fields are always present; missing values are empty strings (empty strings are not signed):

{"retCode":"SUCCESS","sign":"60570E9E22C1CC62C5A425625B2B2260","mchId":"20000001","appId":"","productId":"8001","payOrderId":"ORDER20260918001","mchOrderNo":"ORDER20260918001","amount":"10000","currency":"cny","status":"2","channelUser":"","channelOrderNo":"UP20260918000123","channelAttach":"","paySuccTime":"1789704005000"}

Failure response #

Failure texts are mostly English (as in the old system) and unsigned, for example:

{"retCode":"FAIL","retMsg":"支付订单不存在"}

Orders placed before you switched to this platform cannot be found here (you get 支付订单不存在): rely on the callback for those, or look them up in the old portal.

Example #

mchId=20000001
mchOrderNo=ORDER20260918001

mchId=20000001&mchOrderNo=ORDER20260918001&key=demo-key-NOT-REAL-do-not-use-0001

23A303C6B04E6C7BD44039988E47DC1C

mchId=20000001&mchOrderNo=ORDER20260918001&sign=23A303C6B04E6C7BD44039988E47DC1C

Balance mch_balance #

Request parameters #

Response #

{"mchId":20000001,"balance":500000,"sign":"B7F182CA8F4B91FA5F91A3885B163C86","retCode":"SUCCESS","availableBalance":489800}

• The three numbers are not quoted (as in the old system); amounts are in the currency's minor unit. For merchants opened on this platform (merchant ID starting with M), mchId is a quoted string.
• balance is the total balance; availableBalance is what is available (total minus frozen).
• The signature covers retCode, mchId, balance and availableBalance (numbers as text).

Failures are unsigned, and errDes equals retMsg:

{"errCode":"0010","errDes":"验证签名不通过.","retCode":"FAIL","retMsg":"验证签名不通过."}

Example #

mchId=20000001

mchId=20000001&key=demo-key-NOT-REAL-do-not-use-0001

7695B044D612C28A79D0E33156A4B593

mchId=20000001&sign=7695B044D612C28A79D0E33156A4B593