聚合支付API对接全流程：回调验签、幂等处理与联调要点

一、概念与边界 聚合支付（常被称作四方或服务商模式）在技术上就是把多个上游通道封装成一套统一接口：商户只对接一次，就能按 channel 参数选择不同的支付方式（H5、App、扫码、JSAPI 等）。本文只讲接口层面的工程实现，涉及字段设计、签名验签、幂等与联调，不涉及真实收款业务，也不承诺任何费率或到账时效。

二、下单与查询的基本流程 典型接口分四类：下单、查询、关单、退款。下单请求一般包含 merchant_id、app_id、out_trade_no（商户订单号）、amount（统一用最小货币单位，如分）、channel、subject、client_ip、notify_url、return_url 以及扩展字段 extra。响应返回平台订单号 trade_no 和渠道支付参数：H5 通常是一个跳转 URL，App 是一段预支付串，JSAPI 则是一组前端唤起所需的签名参数。

查询与关单以 out_trade_no 或 trade_no 为键，用于补偿网络超时、用户中途放弃等场景。退款要单独设计退款单号 out_refund_no，并允许部分退款，避免与支付单号混用。

三、签名与回调验签 签名规则要写死在文档里：剔除 sign 字段与空值，参数按 key 的字典序升序拼接成 k=v&k=v 形式，末尾追加密钥后做 MD5/SHA256，或使用 RSA2 私钥签名。注意编码统一为 UTF-8，拼接时不做 URL 编码，传输时才编码。

回调处理必须“先验签、后处理”：校验签名、校验商户号与金额是否与本地订单一致，再落库。验签失败直接丢弃并记录原始报文，不要返回成功。密钥比较建议使用常量时间比较函数，避免时序侧信道。同时校验时间戳与 nonce，超出窗口期的回调视为重放。涉及证书模式时，要做好公钥轮换与双密钥并行期。

四、幂等与状态机 支付回调天然会重复、乱序甚至延迟。核心做法有三条：一是 out_trade_no 建唯一索引，重复请求直接命中已有记录；二是用状态机推进，只允许“待支付→支付中→成功/关闭”这类单向流转，已终态的单子不再变更；三是处理成功后立刻向上游返回 success，缩短重推窗口。

对并发更新使用乐观锁（version 字段）或 SELECT FOR UPDATE，避免两条回调同时把订单改成不同状态。业务侧的发货、加积分等动作要绑定在“状态首次变为成功”的那一次事务里，或使用本地消息表保证只执行一次。

五、联调注意事项 1）网关超时不要立即判定失败，先调用查询接口确认，再决定重试或关单；2）只对幂等接口做重试，采用指数退避；3）notify_url 必须公网可达、不能是内网地址或带鉴权的地址，且与前端 return_url 完全分离，不能靠用户跳转判断支付结果；4）金额单位、时区、字符编码三处最易出错，务必与文档逐字对齐；5）日志脱敏，不打印完整密钥、身份证与卡号；6）沙箱环境要能模拟成功、失败、超时、重复回调四类用例，联调前先用 mock 上游跑通全链路；7）上线前准备对账兜底：定时查询未终态订单，按日拉取对账文件做双向核对。

把签名、幂等、状态机这三件事做扎实，后续换通道或加通道基本只是配置层面的工作。