Stripe 支付链路深度拆解：从 HAR 到 Checkout、PaymentIntent 与 Webhook 对账

最近读到一篇拆 Stripe 协议支付的长文，技术密度很高。它真正有价值的地方，不是某个请求参数本身，而是把一次支付从浏览器、平台后端、Stripe Checkout、PaymentIntent、3DS、Webhook、账务对账串成了一条完整链路。

Stripe 的难点从来不是“创建一个付款链接”。难点在于：用户看到的页面状态、Stripe 的支付状态、你的订单状态、订阅权益状态、账务状态，并不是同一个东西。只要把这些状态混在一起，早晚会遇到用户付款了但没开通、没付款却开通、重复开通、退款后权益没回收、续费失败还在服务这些问题。

这篇按工程视角重新拆一遍：先从 HAR 看链路，再看 Stripe 的对象边界，最后落到字段、状态机、Webhook 幂等和对账。

原参考文：https://blog.caowo.de/posts/stripe-protocol-payment-automation-deep-dive-2026/

先把结论放前面

做 Stripe 集成，最重要的不是会不会调 API，而是能不能回答五个问题：

1. 这笔本地订单，对应 Stripe 的哪个 Checkout Session、PaymentIntent、Invoice、Subscription？
2. 当前状态是页面状态、支付状态、账单状态，还是业务权益状态？
3. 如果 Webhook 重复、乱序、延迟到达，本地状态机会不会被写错？
4. 如果用户中途关闭页面、3DS 超时、银行拒付，本地订单会停在哪里，靠什么补偿？
5. 财务对账时，金额、币种、税费、折扣、退款、手续费能不能从 Stripe 对象一路追到本地订单？

Stripe Checkout 只是入口，PaymentIntent 才是一次支付尝试的状态机，Invoice / Subscription 才是订阅账务的核心，Webhook 才是后端最终一致性的来源。前端回跳只能作为提示，不能作为发货依据。

HAR 应该怎么看

HAR 不是用来“复刻请求”的，它的价值是提供事实时间线。一次 Checkout 失败时，单看后端日志经常是不够的，因为问题可能发生在浏览器初始化、Checkout 页面、3DS 挑战、回跳、Webhook 任意一层。

一个有效的 HAR 复盘，应该先把请求按域名和职责分组：

然后按时间线看四个断点：

HAR 里要重点看的是请求顺序、状态码、对象 ID 和错误码，不要保存原始敏感内容。卡号、CVC、Cookie、Authorization、client secret、邮箱、地址、完整响应体，都不应该进入长期日志。

Stripe 对象模型

把 Stripe 对象关系理清楚，后面的字段才有意义。

对象之间不是平级关系。典型订阅链路是：

User
  -> Customer
  -> Checkout Session
  -> Subscription
  -> Invoice
  -> PaymentIntent
  -> Charge
  -> BalanceTransaction

典型一次性支付链路是：

Order
  -> Checkout Session
  -> PaymentIntent
  -> Charge
  -> BalanceTransaction

如果本地只保存 checkout_session_id，排查首单可能够用，但排查续费、退款、拒付、发票失败就不够了。订阅业务至少要保存 customer_id、subscription_id、latest_invoice_id，一次性支付至少要保存 payment_intent_id 和后续的 charge_id。

Checkout Session 不是支付凭证

很多接入错误都来自把 Checkout Session 当成支付结果。Session 只是结账容器，它说明“用户被引导去做一次结账”，不等于钱已经到账。

关键字段可以按职责分组。

身份和关联字段

client_reference_id 和 metadata.order_id 最好都写。原因很简单：不同 Webhook 事件里出现的对象层级不一样，有的事件主体是 Session，有的是 PaymentIntent，有的是 Invoice。多写一层关联 ID，排查时少查一跳。

金额和商品字段

本地订单建议保存两个金额：amount_expected 和 amount_confirmed。前者是创建 Session 前你认为用户应该付的钱，后者是 Stripe 最终确认的金额。二者不一致时不要自动开通权益，先进入人工或补偿流程。

状态字段

两个常见误判：

1. status=complete 不等于业务可以发货。它只能说明 Checkout 流程完成了，仍要结合 payment_status、PaymentIntent / Invoice 和 Webhook。
2. 用户访问了 success_url 不等于支付成功。浏览器回跳不是可信资金信号，用户关闭页面或网络异常也不应该影响后端最终入账。

创建 Session 的输入边界

后端创建 Checkout Session 时，最危险的不是 Stripe，而是你信了前端传来的字段。

一个比较稳的写法是：前端只提交 plan_id、quantity、可选的优惠码；后端重新读取套餐、价格、库存、活动、用户资格，再创建 Stripe Session。这样即使前端被篡改，也不会出现 1 美元买高价套餐的问题。

PaymentIntent 才是支付状态机

PaymentIntent 描述的是“Stripe 正在尝试收这笔钱”。Checkout 负责用户界面，PaymentIntent 负责支付状态。排查扣款失败、3DS、银行拒付时，最终都要落到 PaymentIntent。

核心字段：

PaymentIntent 状态不能直接平铺到本地订单，要做映射：

这里要特别注意 processing。某些支付方式不是同步完成的，如果你只按前端回跳开通，很容易把还没最终成功的订单当成成功。

3DS 的本质是状态暂停

3DS 不是错误，它是 PaymentIntent 从“可尝试扣款”进入“等待用户认证”的暂停状态。Stripe 会把这个暂停表达在 requires_action 和 next_action 里。

工程上要处理三件事：

1. 前端要能让用户完成认证。
2. 后端不能在认证完成前开通权益。
3. 认证超时或失败后，本地订单要能从 pending 里释放出来。

next_action 不要当成固定结构写死。不同支付方式、不同地区、不同认证类型，下一步动作不一定一样。后端更应该关心最终状态和 Webhook，而不是前端某个页面事件。

失败时重点看 last_payment_error：

对用户展示时，不要把底层错误原样扔出去。比较好的做法是把错误分成几类：余额不足、卡片信息错误、需要认证、银行拒绝、支付方式不支持、系统异常。底层 code 和 decline_code 留给日志、客服和风控分析。

订阅链路要看 Invoice

订阅场景里，很多人只盯着 Subscription，这也会出错。Subscription 描述的是订阅关系，Invoice 描述的是每一期账单，PaymentIntent 描述的是某一张账单的付款尝试。

订阅首单常见链路：

checkout.session.completed
  -> subscription created
  -> invoice finalized
  -> invoice paid
  -> payment_intent.succeeded

续费时用户不一定经过 Checkout，更多是：

invoice.created
  -> invoice.finalized
  -> invoice.payment_succeeded / invoice.payment_failed
  -> customer.subscription.updated

所以订阅权益不能只靠 checkout.session.completed。它只能说明首单 Checkout 完成。后续续费、欠费、取消、试用结束，都要跟着 Invoice 和 Subscription 事件走。

关键字段：

对订阅产品来说，真正应该驱动权益有效期的是 invoice.paid 和 Subscription 的周期字段，而不是用户浏览器是否回到了成功页。

Webhook 的难点是重复和乱序

Stripe Webhook 至少要按“会重复、会乱序、会延迟”来设计。任何只靠内存状态、只处理一次、按接收顺序推进业务状态的实现，都不够稳。

事件表建议这样设计：

处理顺序建议：

1. 先校验签名。
2. 立刻用 stripe_event_id 落库。
3. 如果事件已存在，直接返回成功。
4. 在数据库事务里读取本地订单 / 订阅。
5. 校验金额、币种、对象归属。
6. 推进本地状态机。
7. 写权益变更记录和审计日志。
8. 标记事件处理完成。

不要在 Webhook handler 里做太多慢操作。发邮件、通知、统计、CRM 同步，可以丢异步队列。Webhook handler 的职责是把支付事实可靠落库。

事件类型怎么分工

常见事件不要一股脑都当“支付成功”。

一个典型错误是收到 checkout.session.completed 就立即开通年度订阅。更稳的是：首单订阅以 invoice.paid 作为开通依据，再用 Subscription 的周期字段计算权益结束时间。

状态机要单调推进

本地订单状态最好设计成单调推进，不能让旧事件把新状态覆盖掉。

一次性订单可以这样：

状态推进要校验当前状态。例如订单已经 paid，后来收到一个旧的 payment_intent.payment_failed，不能把订单写回 failed。正确做法是记录事件，但不回退业务状态。

对账要从 Charge 继续往下追

业务系统关心的是“用户有没有付”，财务系统关心的是“钱最终怎么结算”。Stripe 里这两个问题不是同一个对象回答的。

建议本地保留一张支付流水表：

这样月底对账时，不需要从业务订单里硬猜收入。订单管权益，支付流水管资金，发票管账单，余额流水管净额。

常见故障怎么定位

用户说付了钱，但账号没开通

按顺序查：

1. 本地是否有 order_id。
2. 是否保存了 checkout_session_id。
3. Session 的 payment_status 是否为 paid。
4. 是否有 payment_intent.succeeded 或 invoice.paid。
5. Webhook 事件表里是否处理成功。
6. 权益表是否有开通记录。
7. 是否因为金额 / 币种不一致被拦截。

如果 Stripe 已成功、本地 Webhook 失败，补偿任务应该能重放事件或重新查询 Stripe 对象后修复。

用户回到成功页，但后台还是 pending

成功页只说明浏览器回来了。继续看：

• Webhook 是否未到。
• Endpoint 是否签名校验失败。
• 本地事件是否重复插入失败。
• PaymentIntent 是否仍在 processing。
• Invoice 是否还没 paid。

前端此时应显示“支付处理中”，而不是直接显示权益已开通。

订阅续费失败但用户还能用

查三类字段：

• Invoice 是否 payment_failed。
• Subscription 是否进入 past_due、unpaid 或仍在宽限期。
• 本地权益结束时间是否只在首单写入，后续没有跟随 Invoice 更新。

订阅权益不能只在购买时写一次，必须跟着续费、取消、退款、拒付事件调整。

重复开通权益

通常是幂等没做好：

• Webhook 事件重复投递。
• invoice.paid 和 payment_intent.succeeded 都触发开通。
• 前端成功页和 Webhook 各开通一次。
• 重试任务没有检查已有权益记录。

解决方式是给权益变更表加业务唯一键，比如 source_type + source_id。同一张 Invoice 只能延长一次订阅，同一个 PaymentIntent 只能发放一次一次性权益。

自动化应该自动哪一层

支付自动化本身没问题，但要自动化的是自己的后端业务流程，而不是模拟用户绕过支付页面和认证。

适合自动化的部分：

• 创建订单和 Checkout Session。
• 保存 Session / PaymentIntent / Invoice / Subscription 映射。
• Webhook 幂等落库。
• 支付成功后开通权益。
• 支付失败后提醒用户换卡。
• 续费失败后进入宽限期。
• 退款后回收权益。
• 定时补偿 pending 订单。
• 财务对账和差异告警。

不适合自动化的部分：

• 替用户输入卡号。
• 绕过 3DS 或验证码。
• 伪造浏览器或设备环境。
• 批量尝试支付方式。
• 用虚假地址规避税费。
• 保存完整卡号、CVC、原始 HAR。

支付系统的边界很简单：你可以自动化自己的订单、账单、Webhook、对账；不要自动化用户认证和支付安全机制。

最后给一套落地清单

如果从零接 Stripe，我会按这个顺序做：

1. 本地先建 orders、subscriptions、payment_events、payment_ledger 四类表。
2. 创建 Session 前先生成本地订单，前端只传 plan_id。
3. Session 里写 client_reference_id 和 metadata.order_id。
4. payment_intent_data.metadata、subscription_data.metadata 也写本地 ID。
5. 前端成功页只展示“支付处理中 / 已完成”，不直接发权益。
6. Webhook 先落事件表，再幂等推进业务状态。
7. 一次性支付以 payment_intent.succeeded 开通。
8. 订阅以 invoice.paid 开通或续期。
9. 退款、拒付、取消订阅都要反向更新权益。
10. 每天跑补偿任务，扫描 pending、processing、Webhook failed、账务不平的记录。

Stripe 集成真正的专业度，不在于请求写得多像浏览器，而在于每一笔钱都能解释：为什么收、收了多少、谁收的、对应哪个订单、哪个事件触发了权益、失败后停在哪里、退款后怎么回滚、月底怎么对账。

能回答这些问题，支付链路才算真正跑通。