聚合支付API接入科普：下单、回调验签与幂等处理全流程

在支付系统对接中，聚合支付与四方支付常被放在一起讨论。从技术视角看，它们本质上是把多个上游通道封装成统一接口，让业务系统只对接一套下单、查询、退款和回调逻辑。本文只讨论接口层面的工程实现，不涉及真实收款，也不对任何费率作承诺。

一、接入前的准备

接入前先确认四类要素：商户身份参数，如商户号、应用ID；密钥体系，包括对称密钥或商户私钥加平台公钥；回调地址，必须是公网可达的HTTPS地址；联调环境与IP白名单。金额建议统一使用最小货币单位整数，避免浮点数精度问题。日志规范也要提前确定，密钥、证书和敏感字段不得明文落盘。

二、下单接口流程

业务系统先生成商户订单号，要求全局唯一，可采用业务前缀加日期加序列号。然后按文档组装参数：商户号、订单号、金额、币种、支付方式、商品描述、异步通知地址和附加字段。参数排序后签名，通过HTTPS POST提交。平台返回受理结果与支付凭据，可能是二维码串、跳转URL或JSAPI参数。这里要区分受理成功与支付成功，前者只代表请求被接收，不能直接驱动发货。

三、签名与验签

常见签名方式是：除签名字段外，将非空参数按字典序排序，拼成k=v&k=v形式，末尾拼接密钥后做MD5或HMAC-SHA256；也有的通道使用RSA2或SM2对摘要签名。验签时使用平台公钥，按文档剔除空值和签名字段。还要校验时间戳与随机串，服务端维护短期缓存防重放；同时核对商户号与订单号归属，避免跨商户伪造请求。

四、异步回调处理

回调是支付结果的主要来源，必须按不可信输入处理。第一步验签；第二步核对商户号、订单号；第三步核对金额与币种，必须与本地订单一致；第四步判断交易状态，只在成功终态时驱动业务；第五步做幂等，重复通知返回成功但不重复发货；第六步按约定返回成功标识，否则平台会按策略重试。回调地址需公网可达、使用HTTPS、无登录态，并能在秒级返回，耗时逻辑应放入队列异步执行。

五、幂等与状态机

幂等建议做三层：数据库唯一索引，例如商户订单号加交易类型；订单状态机，只允许待支付到支付中再到成功或关闭的合法迁移；分布式锁或去重表，防止并发重复处理。退款同样需要退款单号唯一，并以平台退款结果为准。查询接口用于补偿：定时扫描支付中订单，主动查询并收敛状态，避免只依赖回调。

六、联调注意事项

联调时使用测试环境与测试参数，确认编码为UTF-8、金额单位、时间格式和时区一致。设置合理的连接与读取超时，重试只针对幂等接口。日志脱敏，密钥、证书和完整卡号不入日志。回调域名提前加白，压测关注回调风暴与重复通知。保留请求响应报文与签名原文用于排障。上线前跑通下单、支付、回调、查询、退款、对账的闭环，并核对对账文件与本地账务。

七、上线检查清单

检查密钥轮换机制、监控告警、异常订单人工处理、回调失败补偿和版本变更回归。把接口文档、签名规则、错误码表纳入配置管理，减少因参数差异导致的联调反复。以上为通用技术流程，实际实现以服务商最新接口文档为准。