04｜支付生命周期和参数：一笔 Web3 支付从创建到结算怎么走完

这一篇要解决的问题

上一轮反馈是：“后面继续讲支付的生命周期和参数，不要讲资产，这些我知道。”这一篇按这个方向推进：不展开资产类型，专门拆一笔 Web3 支付从订单创建、支付请求、钱包签名、链上确认、网关监听、订单状态更新、商户履约到结算对账的完整生命周期。

重点放在系统参数上：订单号、金额、币种、网络、收款地址、过期时间、确认数、交易哈希、状态机、回调、幂等键和异常处理。

正文

1. 一笔 Web3 支付不是一笔交易，而是一段生命周期

链上交易只是生命周期中的一个节点。完整支付要从商户创建订单开始，到商户确认可履约、财务可对账、资金可结算结束。

可以先看总流程：

生命周期的关键点是：每一阶段都需要明确输入、输出和状态变化。否则支付系统会在异常场景里混乱，比如用户付了但订单过期、链上到账但网关没监听到、商户重复发货、回调重试导致重复入账。

2. 第一阶段：商户订单参数

支付系统最开始接到的不是链上交易，而是商户业务订单。

商户订单通常包含：

这里要区分两个 ID：

一个订单可能对应多次支付尝试。比如用户第一次支付失败，第二次重新选择网络或钱包；原订单不变，但会生成新的 payment_id。这样可以避免把业务订单和链上支付过程绑死。

3. 第二阶段：支付会话参数

支付网关收到商户订单后，会创建支付会话。支付会话是 Web3 支付系统的核心对象。

一个支付会话通常包含：

支付会话创建之后，前端展示二维码、支付链接或钱包连接按钮。用户看到的内容必须来自支付会话，而不是前端临时拼出来的数据。

这一步最重要的工程原则是：支付请求要由后端生成并可查询。前端可以展示，但不要让前端决定最终收款地址、金额、网络和过期时间。

4. 第三阶段：支付请求参数

支付请求是用户真正拿去付款的东西。它可能是二维码内容、深链接、WalletConnect 请求、网页按钮，或者钱包 SDK 调用。

支付请求需要让钱包或用户知道：

这里有一个常见坑：用户界面显示的是“10 USDC”，链上交易里实际传的是整数最小单位，比如 10000000。系统必须统一处理 decimals，否则会出现金额差错。

另一个坑是币种符号。多个链上都可能有 USDT 或 USDC，合约地址不同。支付系统不能只看 symbol=USDT，必须同时校验 chain_id 和 token_contract。

5. 第四阶段：交易广播和链上确认

用户签名后，交易会被广播到链上。此时支付会话通常进入 pending 或 submitted 状态。

需要记录这些参数：

广播成功不等于支付成功。交易可能长时间 pending，可能失败，可能被替换，可能因为 Gas 不足卡住，可能在合约执行时 revert。

支付网关要区分几类状态：

状态名可以不同，但含义要稳定。商户系统依赖这些状态决定是否发货。

6. 第五阶段：交易监听和订单匹配

网关监听链上交易时，不能只查一个 tx_hash。很多用户会直接转账，不一定通过前端流程提交交易哈希。支付系统需要从链上事件里反向发现付款。

常见监听方式：

订单匹配需要校验这些条件：

匹配成功后，支付会话才能进入 confirmed 或 paid 状态。

7. 第六阶段：状态机和幂等

支付系统一定要有状态机。状态机的作用，是限制状态只能按允许路径变化。

一个简化状态机可以这样设计：

created
  → submitted
  → detected
  → confirmed
  → settled

created
  → expired

submitted / detected
  → failed

confirmed
  → refunded

实际系统里会更复杂，但原则相同：每个状态都要定义进入条件、退出条件和是否可逆。

幂等也很重要。链上监听、回调、用户刷新页面、商户查询接口都可能重复触发同一动作。系统必须保证重复请求不会导致重复发货、重复入账或重复结算。

常见幂等键包括：

Web3 支付里，链上事件天然可能被重复扫描。没有幂等设计，系统迟早会出重复处理问题。

8. 第七阶段：回调和商户确认

支付网关确认支付后，会通知商户系统。这个通知通常叫 webhook 或 callback。

回调内容通常包含：

商户收到回调后，不应该只因为 HTTP 请求到了就发货。还要验证回调签名、检查 event_id 是否处理过、确认订单金额和状态，然后再更新业务订单。

回调必须支持重试。商户服务器可能短暂不可用，网关应该按退避策略重发。商户接口也要支持幂等，重复收到同一个 confirmed 事件时，只返回成功，不重复发货。

9. 第八阶段：异常处理

Web3 支付的大量复杂度来自异常场景。

异常处理要提前写进产品规则。用户支付后才临时决定怎么处理，会让客服、财务和风控都很难办。

10. 第九阶段：结算和对账

支付确认后，商户还需要对账。对账不是确认用户是否付款，而是把业务订单、链上交易、手续费、汇率、结算记录放到同一张表里。

对账记录至少要包含：

对账系统要支持从两边查：财务拿订单号能查到链上交易；客服拿 tx_hash 能查到订单；风控拿地址能查到相关订单和处理记录。

Web3 支付系统成熟与否，很大程度体现在对账能力上。只让用户完成链上转账，还不能算完整商户支付系统。

11. 一张生命周期检查表

看一个 Web3 支付产品时，可以按这张表检查：

这张表可以直接用来读一个支付网关的 API 文档，也可以用来设计自己的支付系统。

小结

1. Web3 支付是一段生命周期，不是一笔孤立链上交易。
2. 关键对象包括 merchant_order_id、payment_id、支付请求、tx_hash、状态机、回调事件和结算记录。
3. 支付会话要明确 chain_id、token_contract、recipient_address、pay_amount、expires_at 和 min_confirmations。
4. 订单匹配必须校验网络、代币、收款地址、金额、过期时间、交易状态和确认数。
5. 状态机、幂等、回调签名、异常处理和对账，是商户支付系统稳定运行的核心。

下一篇预告

下一篇继续沿着支付生命周期展开，进入“支付网关 API 设计”。我们会拆创建支付、查询状态、接收回调、退款、对账这几类接口应该怎么设计，重点看字段、状态码、幂等键和错误码。