三希智付 API 文档

Appearance

常见错误与解决方案 ​

本文档总结了在使用三希智付支付接口过程中的常见错误、原因分析和解决方案。

🚨 签名验证失败 ​

错误现象 ​

json
{
    "code": 9999,
    "msg": "验签失败"
}

常见原因及解决方案 ​

1. 制表符和控制字符问题 ⭐⭐⭐⭐⭐ ​

问题描述： JSON 参数中包含制表符、换行符等控制字符，导致签名字符串不一致。

错误示例：

json
{
    "channelExtra": "{\"Openid\": \"xxx\", \t\"SubAppId\": \"yyy\" }"
}

解决方案：

  1. 使用签名工具的"🧹 清理JSON格式"功能
  2. 手动清理控制字符：
    javascript
    // 清理制表符、换行符等
const cleaned = jsonString.replace(/[\t\r\n]/g, ' ').replace(/\s+/g, ' ').trim();
const formatted = JSON.stringify(JSON.parse(cleaned));

提示

这是最常见的签名失败原因！建议在发送请求前始终清理 JSON 数据。

2. 参数缺失或多余 ​

问题描述：

  • 缺少必需参数（如 signType）
  • 包含不应该参与签名的参数（如 platId）

解决方案：

  • 统一下单API必须包含 signType=MD5
  • 不要包含 platId 参数
  • 参考 统一下单API文档 确认参数列表

3. 时间格式不一致 ​

问题描述： 客户端和服务器使用不同的时间格式。

常见格式：

  • 标准格式：yyyyMMddHHmmss (如：20231019120000)
  • ISO格式：2023-10-19T12:00:00Z

解决方案：

  1. 查看服务器日志确认使用的时间格式
  2. 在签名工具中选择对应的时间格式选项
  3. 确保客户端和服务器使用相同格式

4. 私钥错误 ​

问题描述： 使用了错误的商户私钥。

解决方案：

  1. 确认使用正确的商户私钥
  2. 检查私钥是否包含多余的空格或换行符
  3. 联系技术支持确认私钥

5. 参数值编码问题 ​

问题描述： 特殊字符的URL编码处理不一致。

解决方案：

  1. 确保签名计算时使用原始值（不编码）
  2. 只在HTTP传输时进行URL编码
  3. 使用签名工具验证编码前后的签名

🔧 接口调用错误 ​

1. 请求超时 ​

错误现象：

Connection timeout
Read timeout

解决方案：

  • 检查网络连接
  • 增加请求超时时间
  • 确认接口地址正确

2. 参数格式错误 ​

错误现象：

json
{
    "code": 1002,
    "msg": "参数格式错误"
}

常见原因：

  • JSON格式不正确
  • 必填参数为空
  • 参数类型错误（如金额应为数字）

解决方案：

  1. 验证JSON格式
  2. 检查必填参数
  3. 确认参数类型

3. 商户状态异常 ​

错误现象：

json
{
    "code": 1003,
    "msg": "商户状态异常"
}

解决方案：

  • 联系技术支持检查商户状态
  • 确认商户号是否正确
  • 检查商户是否已开通相应支付方式

🛠️ 调试技巧 ​

1. 使用签名工具 ​

  1. 导入数据： 使用"📋 JSON导入"功能导入请求数据
  2. 清理格式： 点击"🧹 清理JSON格式"
  3. 生成签名： 生成标准签名
  4. 服务器对比： 使用"📋 服务器日志对比"功能

2. 查看服务器日志 ​

服务器日志包含详细的签名信息：

signStr:amount=1&appId=xxx&...&key=xxx
sign:ABCD1234...

3. 逐步排查 ​

  1. 参数完整性： 确认所有必需参数都存在
  2. 参数格式： 检查JSON格式和特殊字符
  3. 签名算法： 验证签名生成步骤
  4. 时间同步： 确认时间格式一致

📋 检查清单 ​

在遇到问题时，请按以下清单逐项检查：

签名相关 ​

  • [ ] 私钥正确无误
  • [ ] 包含 signType=MD5 参数
  • [ ] 不包含 platId 参数（统一下单API）
  • [ ] JSON数据已清理制表符等控制字符
  • [ ] 时间格式与服务器一致
  • [ ] 参数排序正确（ASCII字典序）

请求相关 ​

  • [ ] 接口地址正确
  • [ ] HTTP方法正确（通常为POST）
  • [ ] Content-Type设置为 application/json
  • [ ] 请求体JSON格式正确
  • [ ] 网络连接正常

商户相关 ​

  • [ ] 商户号正确
  • [ ] 应用ID正确
  • [ ] 商户状态正常
  • [ ] 支付方式已开通

🆘 获取帮助 ​

1. 使用签名测试工具 ​

访问 签名测试工具 进行问题诊断。

2. 提供调试信息 ​

在寻求技术支持时，请提供：

  • 完整的请求参数
  • 服务器返回的错误信息
  • 服务器日志（如有）
  • 使用的签名工具生成的签名

3. 常用测试数据 ​

可以使用以下测试数据验证签名算法：

json
{
    "mchNo": "M1748248715",
    "appId": "6834288be4b08df6d75dbd00",
    "mchOrderNo": "ORDER20250111-02",
    "wayCode": "WX_LITE",
    "amount": 1,
    "currency": "CNY",
    "clientIp": "192.168.1.1",
    "subject": "商品标题1",
    "body": "商品描述信息",
    "notifyUrl": "http://example.com/notify",
    "returnUrl": "http://example.com/return",
    "expiredTime": 3600,
    "channelExtra": "{\"Openid\": \"xxx\"}",
    "extParam": "{}",
    "divisionMode": 0,
    "reqTime": "20231019120000",
    "version": "1.0"
}

私钥： your_private_key_here

期望签名： 请使用您的实际私钥计算

📚 相关文档 ​

注意

如果按照本文档的解决方案仍无法解决问题，请联系技术支持并提供详细的错误信息和调试数据。