聚合支付与四方支付 API 对接科普：下单、回调验签、幂等与联调要点

一、整体链路 商户系统发起下单请求，支付网关（聚合支付或四方支付服务商）按路由规则转发到上游通道，通道返回支付凭据（二维码、跳转链接或收银台地址）。用户完成支付后，通道异步回调网关，网关再回调商户；商户依次完成验签、比对订单信息、更新业务状态、返回应答。除了主链路，还有主动查询、退款和对账文件下载等辅助接口，用于兜底与日终核对。理清这条链路，是排查问题的第一步：任何一笔状态不一致，都要先判断问题发生在哪一段。

二、接入前的参数约定 对接前先确认：商户号与密钥的发放方式、签名算法（RSA2、HMAC-SHA256、MD5）、字符集（多为 UTF-8）、金额单位（通常为分，且为整数）、时间格式（常见 yyyy-MM-dd HH:mm:ss），以及网关地址、回调地址、对账文件地址这三类入口。金额单位与字符集最容易出错：把分当成元、把 UTF-8 当成 GBK，都会导致验签失败或金额错位。这些约定必须逐条在文档里核对，不能凭经验假设。

三、请求签名 通用做法是：剔除签名参数本身与空值，按参数名 ASCII 升序拼成 key=value&… 形式，末尾拼接密钥，再做摘要或私钥签名。要注意的细节包括：空字符串与 null 是否参与签名、是否需要对参数值做 URL 编码、是否保留空值参数、签名结果的大小写。不同服务商规则不同，必须严格按文档实现。建议把签名与验签封装成单一公共函数，请求和回调共用一套实现，避免两处逻辑不一致。

四、回调验签 回调是资金状态的源头，验签必须独立且前置：先验签，再比对订单号与金额，最后才修改业务状态。IP 白名单只能作为辅助手段，不能替代验签。为防止重放攻击，应校验时间戳窗口与随机串，超出窗口的通知直接拒绝并记录。验签失败的回调要写入数据库并告警，不能静默丢弃，否则会留下一笔状态不一致的订单。处理完成后必须按服务商要求的格式返回成功标识，否则会触发重复通知；返回内容也不要附带敏感信息。

五、幂等处理 网络抖动、超时重试、通道重复通知，都会造成同一笔订单被多次处理。标准做法是：以商户订单号为唯一键建索引，把通知处理写成“写入幂等表，再让唯一索引冲突的写入直接视为已处理”；订单状态用状态机管理，只允许待支付、已支付、已退款这类单向流转，非法流转直接忽略。回调与主动查询可能同时到达，需要用行锁或版本号避免并发覆盖。退款同理，退款单号也要有唯一约束。

六、联调注意事项 在模拟环境跑完全链路：正常支付、超时未支付、重复回调、验签失败、全额退款、部分退款、对账文件下载。重试要采用指数退避并设上限，避免故障时把服务商接口压垮。日志记录请求报文、响应报文与签名串（密钥脱敏），便于事后复盘；注意服务器时钟同步，时间戳偏差会直接导致验签失败。对账环节建议做三单核对（商户单、通道单、对账单），差异单独成表跟踪，结算周期以对账文件的实际入账时间为准。上线前再走一遍检查清单：密钥是否分离、回调地址是否公网可达、幂等索引是否生效、告警是否接通。