对接必读

在开始联调前，先确认商户号、接口密钥、接口域名已经由平台分配完成。以下内容为商户 API 的对接说明。

调用约定

• GET 接口使用 Query 参数传参。
• POST 接口只接受 JSON 请求体；若不是 JSON，请求会被直接拒绝。
• 所有接口都返回 JSON。
• 排查错误时，请保留响应中的 rid，便于平台定位问题。

安全校验

每次请求都会先经过以下校验：

• 校验固定参数 mch_id、timestamp、nonce、sign
• 校验商户是否存在且处于启用状态
• 校验商户 API IP 白名单（如果已配置）
• 校验请求签名

固定参数

以下字段是所有商户 API 请求都必须携带的公共参数：

参数名	类型	必填	说明
mch_id	integer	是	商户号。对接时请按整数传递
timestamp	integer	是	10 位 UNIX 时间戳。对接时请按整数传递
nonce	string	是	随机串，仅允许字母和数字，长度 6-24 位
sign	string	是	MD5 签名，小写

响应结构

请求成功时：

{
  "code": 200,
  "payload": {
    "id": "C202605040001",
    "trans_id": "ORDER-10001"
  }
}

请求失败时：

{
  "code": 400,
  "rid": "4f25d940-6f6b-4f78-a5a5-4a2f4f0f90ab",
  "errors": {
    "message": "[4f25d940-6f6b-4f78-a5a5-4a2f4f0f90ab] signature verification failed"
  }
}

错误码说明

接口会在 JSON 响应体中返回以下业务状态码：

code	含义
200	成功
400	参数错误、签名错误、业务校验失败
401	未认证
403	无权限
404	接口不存在或资源不存在
406	请求不可接受，例如锁获取失败
429	触发限流
503	服务不可用或系统维护

注意

错误响应的 HTTP 状态码不一定与 code 字段一致。请以响应体中的 code 为准，并记录 rid。

签名算法

当前对接请使用 MD5 签名。RSA 签名暂未开放，请先忽略。

计算规则

1. 取除 sign 外的所有请求参数。
2. 过滤掉空值参数。
3. 按参数名 ASCII 升序排序。
4. 拼接成 key=value&key2=value2 形式的查询字符串。
5. 在最前面加上接口密钥和一个 &，得到待签名字符串：md5_key&key=value...
6. 对整个字符串做 MD5，得到 sign。

例如，请求参数为：

{
  "mch_id": 10001,
  "trans_id": "ORDER-10001",
  "amount": "100.00",
  "channel": "bank",
  "callback_url": "https://merchant.example.com/callback/collect",
  "nonce": "ABC123XYZ",
  "timestamp": 1714819200
}

若接口密钥为 demo_key_123456，则待签名字符串为：

demo_key_123456&amount=100.00&callback_url=https://merchant.example.com/callback/collect&channel=bank&mch_id=10001&nonce=ABC123XYZ&timestamp=1714819200&trans_id=ORDER-10001

将该字符串做 MD5，即得到最终的 sign。

RSA 签名

暂未开放。

联调建议

• POST 接口请显式设置 Content-Type: application/json
• 回调地址请返回纯文本 success
• 代收与代付的查询返回格式略有差异，详见各接口说明
• 若遇到 Insufficient channel permission: xxx，表示商户没有该通道权限