支付接入流程避坑清单

支付接入的难点不在“能付成功”，而在“付失败、付重复、付到一半断掉”时系统是否仍然自洽。很多问题在测试环境不会暴露，因为测试环境很少模拟超时、重复回调和状态乱序。下面给出一套以状态为核心的自查框架。

一、先把状态机画清楚

接入前必须明确本地订单有哪些状态、每个状态由什么事件驱动、哪些状态是终态。常见错误是把“已支付”当成唯一判断依据，忽略“支付中”“部分成功”“已关闭”等中间态。状态机不清，后续所有异常处理都会变成打补丁。

建议做法是列出所有可能事件：发起支付、收到成功通知、收到失败通知、超时未收到通知、主动查询返回成功、主动查询返回未支付、发起退款、退款完成。然后为每个事件写明“当前状态到目标状态”的迁移规则，并标注哪些迁移必须拒绝。把这张表作为评审材料，比口头讨论有效得多。

二、幂等与重复通知

支付侧的通知可能重复投递，也可能乱序到达。系统必须做到同一笔业务重复收到成功通知时结果一致，且不产生二次记账。实现上通常用业务单号加通知类型做幂等键，处理前先查是否已处理过。

要注意幂等判断与业务写入必须在同一事务边界内，否则并发下仍可能重复。另一个易漏点是乱序：先收到成功再收到“处理中”，若后者覆盖前者就会把已支付订单改回未支付。规则应是状态只能单向推进，低优先级事件不得覆盖高优先级终态。

三、主动查询与超时兜底

不能只依赖被动通知。网络抖动、通知丢失都会让订单悬在中间态。应设计定时主动查询，对超过一定时长仍处于支付中的订单发起状态确认，并按查询结果推进状态。查询本身也要幂等，且要有退避策略，避免对下游造成压力。

超时关闭要谨慎：关闭前必须先查询确认未支付，不能仅凭本地计时器关闭。否则可能出现用户已付款但订单被关的尴尬局面。关闭后若再收到成功通知，要有补偿路径而不是直接丢弃。

四、对账与差异处理

对账不是财务专属，接入方也要有日终比对能力。做法是以业务单号为主键，比对本地记录与支付侧流水，输出三类差异：本地有支付侧无、支付侧有本地无、金额或状态不一致。每类差异要有明确的处理人和处理时限。

差异处理要留痕，记录发现时间、核对过程、结论。不要用“人工改数据库”方式抹平差异，那会让后续对账失去基准。

五、异常路径自查清单

状态机是否覆盖全部中间态；重复成功通知是否结果一致；乱序通知是否会被终态拒绝；幂等判断与写入是否同事务；是否有主动查询兜底；关闭前是否先查询确认；关闭后收到成功是否有补偿；对账是否按单号比对；差异是否有分类与留痕；退款是否有独立状态跟踪。十项自查通过，再考虑放量。