商户接口签名规则

商户接口使用统一的 JSON 外层结构。业务参数先序列化为 JSON，再编码为十六进制字符串。

请求格式

请求头：

Content-Type: application/json

请求体：

字段	类型	必填	说明
version	string	是	固定为 v1
timestamp	int64	是	Unix 秒级时间戳，服务端按 5 分钟有效期校验
merchant_key	string	是	商户标识
data	string	是	业务参数 JSON 的小写十六进制编码
sign	string	是	请求签名，小写 MD5 字符串

签名步骤

1. 将业务参数序列化为紧凑 JSON，不添加无业务意义的空格或换行。
2. 将 JSON 的 UTF-8 字节编码为小写十六进制，得到 data。
3. 按以下顺序直接拼接签名原文，不添加分隔符：

data + version + timestamp + merchant_secret

1. 对签名原文计算 MD5，并将摘要转为小写十六进制字符串。

伪代码：

business_json = compact_json(business_data)
data = hex(utf8(business_json))
sign_text = data + "v1" + timestamp + merchant_secret
sign = lowercase_hex(md5(sign_text))

完整请求示例：

{
  "version": "v1",
  "timestamp": 1782864000,
  "merchant_key": "YOUR_MERCHANT_KEY",
  "data": "7b2272616e646f6d223a2231373832383634303030227d",
  "sign": "SIGNATURE_LOWERCASE_MD5"
}

示例中的 data 解码后为：

{
  "random": "1782864000"
}

响应格式

成功响应：

{
  "code": 0,
  "message": "ok",
  "data": {}
}

失败响应的 data 为 null：

{
  "code": 1005,
  "message": "SIGNATURE INVALID",
  "data": null
}

常见认证错误

错误码	说明
1002	数据解析、版本、十六进制数据或业务参数无效
1004	请求 IP 不在商户白名单中
1005	签名不匹配
1000001	商户不存在、已停用或所属品牌已停用

注意事项

• timestamp 使用秒，不是毫秒。
• data 必须使用小写十六进制；计算签名时使用传输请求中完全相同的 data 字符串。
• 所有商户签名接口均使用 HTTP POST。