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

Question

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

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

我的问题是：

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

感谢您的帮助！谢谢。

Answer 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。

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