Stripe Webhooks：Invoice.paid 与 Checkout.Session.Completed

Posted 2023-03-21

【中文标题】Stripe Webhooks：Invoice.paid 与 Checkout.Session.Completed

【英文标题】：Stripe Webhooks: Invoice.paid vs Checkout.Session.Completed

【发布时间】：2021-02-24 19:20:13

【问题描述】：

我使用 Stripes 的 webhook 并希望在客户成功“支付账单”时收到通知。我遇到了两个 webhook，我认为它们都可以完成这项工作：

Webhook “invoice.paid” - 根据 Stripe 文档：每当发票付款尝试成功或发票被标记为带外付款时发生。 Webhook "checkout.session.completed" - 根据 Stripe 文档：在 Checkout Session 成功完成时发生。

我的问题是：

我不明白“invoice.paid” webhook 的第二部分：“发票被标记为带外付款”->“带外”是什么意思？这是否被视为成功付款？ 关于“checkout.session.complete” -> 如果付款失败，也会发生这种情况 - 正确吗？ 我应该考虑哪些 webhook（或者是否有其他 webhook）来查看“客户已成功支付账单”状态？ 而且，我真的不知道争议是否应该被视为成功付款：一方面，我得到了一个 invoice.paid 的 webhook，另一方面，我得到了一个 charge.dispute.created 的 webhook .天哪……

感谢您的帮助！谢谢。

【参考方案1】：

我不明白“invoice.paid”网络钩子的第二部分：“发票被标记为带外付款”->“带外”是什么意思？这算不算成功付款？

这特别是指标记发票paid out of band（即，客户在 Stripe 之外向您付款，而您希望将 Stripe 发票标记为已支付不收取款项）。这不会涉及实际付款，但会将发票转换为status=paid，因此会触发此事件。

关于“checkout.session.complete” -> 如果付款失败，也会发生这种情况 - 正确吗？

此事件仅表明 Checkout 会话已完成。根据结帐时使用的mode，这可能涉及也可能不涉及付款。如果需要立即付款，则只有在付款成功时会话才会完成。例如mode=setup 或mode=subscription 免费试用不涉及立即付款。不过，试用订阅会创建 0 美元的发票并触发 invoice.paid。

我应该考虑哪些 webhook（或者是否有其他 webhook）来查看 状态“客户支付成功”？

这取决于您所说的“付费”和“账单”是什么意思。如果您的意思是专门针对发票（无论是否与订阅相关），那么invoice.paid 是一个不错的选择。然后，您可以过滤大于 0 美元等的金额，以进一步限制“付费”方式。

而且，我真的不知道是否应该将争议视为 是否成功付款：一方面，我得到了一个 invoice.paid 的 webhook， 另一方面，我得到了一个charge.dispute.created webhook。

争议不是付款，应该是完全独立的讨论。您只能在付款后提出争议。建议先阅读docs on disputes。

总结：你真正想做的是什么？这些事件是相关的，有时会重叠，但并非总是如此。这在很大程度上取决于您在做什么。

【讨论】：

首先非常感谢您！ 1) 2) 3) Webhook：客户正在订阅（mode='subscription' 并且没有任何线索）并获得积分（通过 webhook）作为回报。目标是仅在成功支付发票后才能充值。据我了解，在这种情况下，两个 webhook 都是可能的。但是，在我看来，网络钩子“invoice.paid”似乎更合适，因为它更好地针对实际的“完成的付款/交易”。同意？ 4) 太棒了 - 感谢您的文档。

在这种情况下，我同意这可能更简单，因为它还涵盖了您每个月/年/任何时期的续订，而不是拆分第一张/经常性发票的逻辑。请注意，如果您开始使用一次性发票，这也会触发，因此您将来可能需要额外检查 subscription 属性。 stripe.com/docs/api/invoices/object#invoice_object-subscription

超级 - 谢谢！