对接必读

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

调用约定

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

安全校验

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

• 校验固定参数 mch_id、timestamp、nonce、sign
• 校验商户是否存在且处于启用状态
• 校验商户 API IP 白名单（如果已配置）
• 校验指定 API KEY 是否属于该商户、处于启用状态且拥有当前接口能力
• 校验请求签名

固定参数

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

参数名	类型	必填	说明
mch_id	integer	是	商户号。对接时请按整数传递
timestamp	integer	是	10 位 UNIX 时间戳。对接时请按整数传递
nonce	string	是	随机串，仅允许字母和数字，长度 6-24 位
sign	string	是	MD5 签名，小写
api_key_id	string	否	API KEY ID（26 位 ULID）。使用非默认 API KEY 时必传，且必须参与签名

API KEY 选择

• 不传 api_key_id 时，系统使用商户的默认 API KEY 验签并检查其能力，兼容已有对接。
• 使用控制台中新建的非默认 API KEY 时，必须传入该 KEY 对应的 api_key_id，并使用该 KEY 的密钥计算签名。
• API KEY 必须已启用，并拥有当前接口所需的能力；否则请求会被拒绝。

响应结构

请求成功时：

{
  "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	服务不可用或系统维护

注意

API 调用成功与否，只通过 code 判断。 code=200 表示 API 调用成功，其他的 code 值一律表示 API 调用出错，API 调用出错请以响应体中的 code 为准，具体的出错原因参见 errors.message 给的错误提示，并记录 rid。

签名算法

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

计算规则

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

例如，请求参数为：

{
  "mch_id": 10001,
  "api_key_id": "01M0D4WJWZZYVH26943FP99ZV8",
  "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&api_key_id=01M0D4WJWZZYVH26943FP99ZV8&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，表示商户没有该通道权限