一次 API 购买为何会留下两份付款授权
API 请求超时重试后,同一笔购买可能留下两份有效的 x402 付款授权。两个流程独立签名时,常见预防措施可能无法协调,callx402 可在本地根据结算证据判定为五种状态之一。
AI 深度解读
一次 API 调用超时,客户端重试后,同一笔购买留下了两份有效的付款授权。请求超时只说明客户端没等到响应,无法据此判断钱有没有付。两份授权都可能被结算,问题甚至要到对账时才浮出来。
作者给出的处理办法是,先汇总已有的结算证据,再决定该等、该结算,还是该交给人工。这篇最值得前端和全栈开发者带走的,是怎么给支付重试补上这一步。
为什么有幂等键,还会留下两份授权?
这个案例来自 x402-foundation/x402 的 issue #4198。在 x402 里,买方签发付款授权,代表卖方可以凭这份授权发起资金转移。授权已经签好和资金已经结算,是两个不同的状态。对于同一笔购买,两份签名可以各自有效,卖方可能结算两次,买方也可能用错授权。两份授权还可能一直悬着,直到有人对账或介入排查。
限额、幂等键和客户端预留额度,都依赖相关流程能看到某种共享状态。例如,两次请求命中同一条幂等记录,服务端就有机会识别它们属于同一笔购买。但如果两条独立流程各自签名,彼此看不到对方的付款意图,共享的预留机制就无从触发。此时补上预防措施,也无法回答眼前这笔购买究竟付了几次。
手里有两份授权,下一步怎么决定?
作者团队在 x402 诊断工具 callx402 里加了一个 duplicate_payment_risk 动作。它在本地读取同一笔购买的结算证据,在继续签名或结算之前,给出五种判断。
- 两笔结算都已确认时,返回
CONFLICT。这可能是重复结算,交给操作人员处理。 - 只有一笔结算确认时,将这笔购买视为已支付。
- 只有待确认的结算时,继续等待。
- 有证据表明还没发起结算时,只能使用已有授权结算。
- 拿不到可用证据时,返回
UNKNOWN,默认阻止后续操作。
最容易混淆的是最后两种。查不到结算证据,不能当成从未发起过结算。 前者可能只是查询失败或记录缺失,后者才允许使用已有授权继续。作者还提到,RevRule 核对的是应付金额和实付金额,属于后续的付款核验环节。
我的判断
这套做法说得最清楚的是重试边界。接口超时可以触发查询,但付款是否要继续,得由结算证据决定。对于能统一管理购买记录的团队,服务端幂等依然适合优先用来减少重复签名。诊断流程则能接住已经出现两份授权的购买。
作者用参照 issue 记录构造的测试样本验证了判断逻辑,测试没有联网,也没有发生真实支付。它验证了给定证据时工具会怎样判断。生产环境能拿到多少证据、证据冲突时能否稳定归到同一笔购买,以及这种做法能减少多少重复结算,原文都没有给出数据。五种状态可以作为设计参考,接入时仍要看自己的支付链路能提供哪些可核验记录。
能拿来做什么
- 前端遇到付费 API 超时时,可以先显示「支付状态待确认」,让用户查询当前购买的状态,避免重试按钮直接触发新签名。
- Node 服务可以按购买记录关联已签授权和已知的结算状态,让重试流程有据可查。查询失败时保留未知状态,避免把缺失记录误判为从未结算。
- 给支付重试补测试时,可以先用本地样本覆盖五种结果,尤其要断言
CONFLICT和UNKNOWN都会阻止自动继续付款。