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

Question

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

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

我的问题是：

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

我感谢您的帮助！谢谢。

Answer 1

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

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

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

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

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

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

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

争议不是付款，应该完全单独讨论。您只能在付款后提出争议。建议首先阅读有关争议的文档。

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