API签名认证对接文档

1. 快速接入流程

获取密钥：登录商户后台 - 支付管理 - 收银台，页面会展示 client-id 和 client-key

配置调试工具：推荐使用 Postman 进行调试（见第4节）

生成签名：使用 client-id + client-time + client-key + body 拼接，MD5后转大写

发起请求：携带正确的 Header 与 Body 调用接口

2. 请求参数说明

2.1 Header 参数

参数名称	是否必填	说明	示例
client-id	是	应用ID，请求方身份标识	EW_N5119728343
client-time	是	时间戳（秒级，10位数字）	1758101436
client-sign	是	签名（32位MD5大写）	7234A7113E95D263F9B69D27994B5FDC

2.2 Body 参数

格式：JSON格式字符串

编码：UTF-8

要求：紧凑格式，无多余空格和换行

示例：{"merchant_code":"EW_N7228915787","pay_model":0,"order_amt":0.01}

2.3 安全说明

⚠️ 重要安全提示：

client-key 仅用于本地签名计算，绝不要放入请求头中传输

client-key 应妥善保管，建议使用环境变量或密钥管理服务存储

所有请求必须使用 HTTPS 传输

服务端会验证时间戳，超过 5分钟 的请求将被拒绝

3. 签名生成规则

3.1 签名算法

签名原文 = client-id + client-time + client-key + body
client-sign = MD5(签名原文).toUpperCase()

注意事项：

拼接时无分隔符，直接连接

顺序必须固定，不可调换

Body为空时，签名原文为：client-id + client-time + client-key

所有参数使用 UTF-8 编码

3.2 完整示例

接口信息：

接口地址：https://dev.liantuofu.com/open/pay

请求方式：POST

参数准备：

client-id: EW_N5119728343

client-key: 42059ece3c4944290641faa0f8f24b58

client-time: 1758101436

body: {"merchant_code":"EW_N7228915787","pay_model":0,"order_amt":0.01}

签名计算过程：

签名原文：
EW_N5119728343175810143642059ece3c4944290641faa0f8f24b58{"merchant_code":"EW_N7228915787","pay_model":0,"order_amt":0.01}

MD5计算：
md5 = 7234a7113e95d263f9b69d27994b5fdc
client-sign = 7234A7113E95D263F9B69D27994B5FDC（转大写）

4. Postman 调试指南（推荐）

4.1 自动签名脚本配置

步骤1： 创建新请求

Method: POST

URL: https://dev.liantuofu.com/open/pay

步骤2： 在 Headers 中添加：

client-id: EW_N5119728343

注：client-time 和 client-sign 会由脚本自动生成

步骤3： 在 Pre-request Script 标签页粘贴以下代码：

步骤4： 在 Body 中选择 raw → JSON，输入请求参数：

{
    "merchant_code": "EW_N7228915787",
    "pay_model": 0,
    "order_amt": 0.01
}

步骤5： 点击 Send 发送请求即可

5. 代码示例

5.1 cURL

5.2 Python

5.3 Java

5.4 Node.js

6. 响应格式

6.1 成功响应

{
    "code": 200,
    "msg": "success",
    "data": {
        "order_no": "20250110101258590000069181",
        // 其他业务字段...
    }
}

6.2 错误响应

{
    "code": 400,
    "msg": "签名验证未通过"
}

6.3 错误码说明

错误码	说明
200	请求成功
400	错误信息

7. 常见问题与调试

签名验证失败排查

排查步骤：

验证签名算法

使用文档示例参数（第3.2节）验证你的签名算法

确认生成的签名是否为：7234A7113E95D263F9B69D27994B5FDC

检查密钥配置

确认 client-key 是否正确（区分测试/生产环境）

验证是否从商户后台 - 支付管理 - 收银台获取的最新密钥

JSON格式验证

确保JSON为紧凑格式，无空格换行

字段顺序必须与签名时保持一致

示例：{"merchant_code":"EW_N7228915787","pay_model":0,"order_amt":0.01}

时间戳检查

必须是秒级时间戳（10位数字），不是毫秒级（13位）

服务端会拒绝超过5分钟的请求

调试检查清单

client-id 从商户后台获取且正确

client-key 从商户后台获取且正确（没有混淆环境）

JSON 格式紧凑，无空格

字符编码为 UTF-8

使用 HTTPS 协议

MD5 结果已转大写

client-key 没有放入请求头

其他常见问题

Q: Body为空时如何签名？

签名原文为：client-id + client-time + client-key

Q: 如何处理中文和特殊字符？

所有中文直接使用，不要转义为Unicode

确保全链路使用 UTF-8 编码

Q: 本地测试成功但线上失败？

检查是否混用了测试/生产环境的密钥

验证服务器时间是否准确（可能存在时区问题）

确认生产环境的 client-id 和 client-key 配对正确

附录：签名验证工具

您可以使用以下在线工具验证MD5计算：

https://www.cmd5.com/

https://tool.chinaz.com/tools/md5.aspx

验证示例：

输入：EW_N5119728343175810143642059ece3c4944290641faa0f8f24b58{"merchant_code":"EW_N7228915787","pay_model":0,"order_amt":0.01}
输出：7234A7113E95D263F9B69D27994B5FDC

API签名

API签名认证对接文档#

1. 快速接入流程#

2. 请求参数说明#

2.1 Header 参数#

2.2 Body 参数#

2.3 安全说明#

3. 签名生成规则#

3.1 签名算法#

3.2 完整示例#

4. Postman 调试指南（推荐）#

4.1 自动签名脚本配置#

5. 代码示例#

5.1 cURL#

5.2 Python#

5.3 Java#

5.4 Node.js#

6. 响应格式#

6.1 成功响应#

6.2 错误响应#

6.3 错误码说明#

7. 常见问题与调试#

签名验证失败排查#

调试检查清单#

其他常见问题#

附录：签名验证工具#