第一步:选择接口版本
接入前先确定项目使用新版还是旧版接口。新版文档使用 RSA 签名并提供统一下单、查单、退款等接口;旧版接口主要用于已有系统兼容,采用 MD5 签名。两个版本的请求地址和签名规则不能混用。
第二步:准备订单数据
商户订单号必须在自己的系统中唯一。金额建议使用固定两位小数的字符串保存和传递,不要使用可能产生浮点误差的计算方式。通知地址应为公网 HTTPS 地址,并避免跳转、登录验证或输出调试信息。
第三步:在服务端生成签名
签名必须在服务端完成。按照当前接口文档规定筛选字段、排序并拼接待签名内容,再使用对应算法处理。商户私钥或旧版密钥不能放进网页 JavaScript、APP安装包、公开仓库或日志。
第四步:发起支付
服务端提交订单后,应先判断接口返回状态,再根据返回内容展示支付链接或二维码。不要把“接口已返回支付地址”当成“订单已支付”,最终结果仍需等待通知或主动查询。
第五步:处理异步通知
- 读取平台实际发送的原始参数。
- 先验证签名,再核对商户订单号、平台订单号和订单金额。
- 只允许未支付订单变更为已支付,重复通知不得重复发货或充值。
- 业务处理成功后,返回文档要求的成功响应。
第六步:增加主动查单
通知可能因网络、证书、服务器超时或程序异常而失败。对于长时间停留在待支付状态的订单,可调用订单查询接口核验最终状态,但查单同样需要验签和金额校验。
上线检查清单
- 成功支付、取消支付和超时订单均已测试。
- 同一通知重复发送不会重复处理业务。
- 通知日志不记录完整密钥、私钥或敏感付款信息。
- 金额、订单归属和商品交付均以本地订单为准进行核对。
- 生产环境与测试环境的域名、密钥和回调地址没有混用。