對接文件
本頁還沒有繁體中文版本，下面是简体中文內容。

代收接口 compat1（老协议）

原来已经按老系统代收接口接好的商户用这一套：商户号、密钥、签名、参数、应答都和原来一样，只把网关地址换成本平台的 https://api.xx2system.xyz。本平台新开的商户（商户号 M 开头）也用这一套，商户号原样传。

公共规则

接口地址应答
下单https://api.xx2system.xyz/api/pay/create_orderapplication/json
查单https://api.xx2system.xyz/api/pay/query_orderapplication/json
查余额https://api.xx2system.xyz/api/account/mch_balancetext/plain;charset=UTF-8
前置姓名页（付款人打开）https://api.xx2system.xyz/api/pay/input_nametext/html;charset=UTF-8
前置姓名页提交（付款人提交）https://api.xx2system.xyz/api/pay/input_name/submittext/html;charset=UTF-8

下单 create_order

请求参数

参数必填规则说明
mchId是数字；或本平台新开商户的号（MCH＋5 位数字），原样传商户号
productId是只能是数字老商户原来用的哪个就填哪个；正式产品ID编码请联系客服提供
mchOrderNo是只许字母、数字、下划线、连字符；最长 60（按 UTF-16 码元算，表情和生僻字算 2）商户单号，同一商户不能重复
amount是整数，按货币最小单位，大于 0金额，按货币最小单位
notifyUrl是最长 512（按 UTF-16 码元算，表情和生僻字算 2）支付结果回调地址（不校验格式；不能有 &）
subject是最长 64（按 UTF-16 码元算，表情和生僻字算 2）商品标题
body是最长 256（按 UTF-16 码元算，表情和生僻字算 2）商品描述
sign是32 位十六进制，见签名签名（MD5），见「签名」
param2否最长 64（按 UTF-16 码元算，表情和生僻字算 2）付款人姓名；不传时按通道设置用固定姓名或前置姓名页
param1否最长 64（按 UTF-16 码元算，表情和生僻字算 2）您自己的附加值，回调原样带回
extra否最长 512（按 UTF-16 码元算，表情和生僻字算 2）扩展参数，个别通道要求
clientIp否最长 128（按 UTF-16 码元算，表情和生僻字算 2）付款人 IP；不传取请求来源
returnUrl否最长 512（按 UTF-16 码元算，表情和生僻字算 2）付款后返回的页面，个别通道使用
device否最长 64（按 UTF-16 码元算，表情和生僻字算 2）设备信息
currency否最长 3（按 UTF-16 码元算，表情和生僻字算 2）币种，不校验取值，不传是 cny
reqTime否yyyyMMddHHmmss请求时间；不校验和现在差多少
version否只能是 1.0接口版本
appId否不要传（传了非空值回「应用不存在」）应用 ID

成功应答

只有两种 payMethod：

{"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":"中国工商银行"}}

应答签名时 payParams 当作一个值：第一层的键排好序、紧凑写成 JSON 再参与签名（见 签名）。

失败应答 

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

前置姓名页

通道要求付款人姓名、而您没传 param2 时，下单成功应答是 formJump，payUrl 指向本平台的姓名页 https://api.xx2system.xyz/api/pay/input_name?t=…。付款人在这页填好姓名，再跳到付款页或看到收款卡信息。页面只有中文。对您来说和普通跳转一样处理，不用改代码。

示例

示例密钥（假的）：demo-key-NOT-REAL-do-not-use-0001

参数

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

sign

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

请求参数

参数必填规则说明
mchId是数字；或本平台新开商户的号（MCH＋5 位数字），原样传商户号
mchOrderNo二选一商户单号，同一商户不能重复
payOrderId二选一订单号（按它查不到时再当商户单号查一次）
executeNotify否true 时，订单已成功就再补发一次回调
sign是32 位十六进制，见签名签名（MD5），见「签名」
reqTime否yyyyMMddHHmmss请求时间；不校验和现在差多少
version否只能是 1.0接口版本

成功应答

下面 14 个字段每次都有，没有值的是空串（空串不参与签名）：

参数说明
retCodeSUCCESS 或 FAIL
sign签名（MD5）
mchId商户号
appId应用 ID（一般是空串）
productId正式产品ID编码请联系客服提供
payOrderId商户单号（和老系统一样，这里放的是商户单号）
mchOrderNo商户单号
amount下单金额（最小单位）
currency币种
status订单状态，见下表
channelUser渠道用户
channelOrderNo上游单号
channelAttach上游附加数据
paySuccTime成功时间，毫秒数；没有时是空串
状态意思
-2已关闭
-1支付失败
0初始（还没去付款）
1支付中
2支付成功
3业务完成（回调您成功之后）
4已退款或冲正
{"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"}

失败应答

失败原话大多是英文（和老系统一样），不带 sign，例如：

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

切换到本平台之前下的单，在本平台查不到（回 支付订单不存在）：那些单以回调为准，或到老后台查。

示例

示例密钥（假的）：demo-key-NOT-REAL-do-not-use-0001

参数

mchId=20000001
mchOrderNo=ORDER20260918001

签名串

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

sign

23A303C6B04E6C7BD44039988E47DC1C

请求正文

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

查余额 mch_balance

请求参数

参数必填规则说明
mchId是数字；或本平台新开商户的号（MCH＋5 位数字），原样传商户号
sign是32 位十六进制，见签名签名（MD5），见「签名」
reqTime否yyyyMMddHHmmss请求时间；不校验和现在差多少
version否只能是 1.0接口版本

应答 

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

失败时不带 sign，errDes 和 retMsg 相同：

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

示例

示例密钥（假的）：demo-key-NOT-REAL-do-not-use-0001

参数

mchId=20000001

签名串

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

sign

7695B044D612C28A79D0E33156A4B593

请求正文

mchId=20000001&sign=7695B044D612C28A79D0E33156A4B593