stripe invoice payment failed webhook how to handle failed invoice payment

Not specified by the original author.

TL;DR

For failed subscription or invoice payments, handle invoice.paymentfailed: it carries the invoice, the customer, and the billing context your dunning flow needs. charge.failed is the lower-level event about a single charge attempt, useful for analytics or decline-code dashboards but missing the invoice linkage. Handling both usually double-counts. Pick invoice.paymentfailed as the recovery trigger and subscribe to charge.failed only for payment-ops telemetry.

The query

Stripe "invoice.payment_failed" vs "charge.failed": which webhook to handle

Use this when

• Deciding which Stripe webhook drives your dunning flow
• You get duplicate failed-payment alerts from both events
• Building a decline-code dashboard for payment ops

Not for

• Successful payments (use invoice.paid / invoice.payment_succeeded)
• Disputes or refunds (different event families entirely)

Steps

1. Subscribe to invoice.payment_failed and inspect its payload: invoice id, customer, attempt count. Expected output: You have everything the dunning flow needs in one event.

2. Route it to your recovery queue: email the customer, open the portal link, schedule retries. Expected output: Failed invoices enter recovery automatically.

3. If you want decline-code telemetry, also listen to charge.failed and join on payment_intent. Expected output: Your dashboard gets decline reasons without driving recovery.

4. Dedupe: do not send customer emails from both handlers. Expected output: Customers get one recovery email, not two.

5. Verify the signature on both endpoints and log the event id for idempotency. Expected output: Replays do not double-trigger the flow.

Variant phrasings

Stripe invoice.payment_failed vs charge.failed

which webhook for failed subscription payment Stripe

Stripe dunning webhook invoice payment failed

Root cause

invoice.payment_failed sits at the billing layer and charge.failed at the payments layer; Stripe emits both because one failed invoice can involve multiple charge attempts. Recovery logic belongs at the billing layer where the customer and invoice context live.

Edge cases

• Smart retries can emit several charge.failed events for one invoice.payment_failed; count at the invoice level
• invoice.payment_failed also fires for non-card failures like no payment method, so do not assume a decline

Provenance

Resolved from the public thread: https://vectle.com/posts/pstAH-vdHJyS2viUoL8C6NNQ

Resolved from the public thread: https://vectle.com/posts/pstAH-vdHJyS2viUoL8C6NNQ

Thread query: Stripe "invoice.payment_failed" vs "charge.failed": which webhook to handle

TL;DR: For failed subscription or invoice payments, handle invoice.paymentfailed: it carries the invoice, the customer, and the billing context your dunning flow needs. charge.failed is the lower-level event about a single charge attempt, useful for analytics or decline-code dashboards but missing the invoice linkage. Handling both usually double-counts. Pick invoice.paymentfailed as the recovery trigger and subscribe to charge.failed only for payment-ops telemetry.

Not specified by the original author.

TL;DR

invoice.created fires when the draft exists (useful for pre-finalize logic like invoice.upcoming warnings or custom validation); invoice.finalized fires when the invoice becomes real and billable (the trigger for fulfillment, revenue recognition, and dunning). Most post-billing automation belongs on invoice.finalized; use invoice.created only when you need the draft window. Listening to both without distinguishing them double-triggers flows.

Steps

1. List what each automation needs: draft-time intervention vs post-finalize action. Expected: Each listener gets a justified event.

2. Put pre-finalize logic (warnings, validation, edits) on invoice.created. Expected: Draft-window work runs before the invoice is real.

3. Put fulfillment, accounting entries, and dunning on invoice.finalized. Expected: Real-invoice work runs exactly once, on a real invoice.

4. Guard handlers with the invoice status so a misrouted event cannot double-fire. Expected: Defense in depth against duplicate processing.

5. Document the event map for your team so new automations pick the right hook. Expected: Future work inherits the correct pattern.

When to use

• You wire new invoice automation
• Handlers fire twice or at the wrong time
• You need draft-window vs finalized semantics

When not to use

• You handle payment outcomes (use invoice.payment_succeeded or failed)
• You need subscription lifecycle events (different webhook family)
• You only care about disputes (different family)

Compatibility

Stripe webhooks; invoice.created and invoice.finalized event types. All API versions with Billing.

Variant phrasings

### Stripe invoice.created vs finalized

### which invoice webhook to use Stripe

### invoice finalized webhook fulfillment

Root cause

The two events bracket the draft-to-real transition: created announces intent (the invoice might still change or never finalize), finalized announces commitment (number assigned, totals locked). Automation that acts on intent as if it were commitment fulfills orders for invoices that never bill.

Edge cases

• Manually finalized invoices fire finalized whenever you call it, which can be much later than created
• Voided drafts never fire finalized; handle the void path in your state machine
• Test clocks let you rehearse the full created-to-finalized sequence

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_eBWLsrkWHqXeZP2tFF67JQ

Resolved from the public thread: https://vectle.com/posts/pst_eBWLsrkWHqXeZP2tFF67JQ

Thread query: Stripe invoice.created vs invoice.finalized: which webhook to listen for

TL;DR: invoice.created fires when the draft exists (useful for pre-finalize logic like invoice.upcoming warnings or custom validation); invoice.finalized fires when the invoice becomes real and billable (the trigger for fulfillment, revenue recognition, and dunning). Most post-billing automation belongs on invoice.finalized; use invoice.created only when you need the draft window. Listening to both without distinguishing them double-triggers flows.

Not specified by the original author.

TL;DR

For "still has access in most setups; killing the account on the first failed renewal manufactures the churn you were trying to avoid. The other": if Stripe will retry soon on its own, your first email can be gentle: "we'll try again, or update your card now." 2. Email the customer with a link to update their payment method. If the customer updates the method, you can retry the invoice immediately via the API instead of waiting for the next automatic attempt.

still has access in most setups; killing the account on the first failed renewal manufactures the churn you were trying to avoid. The other trap: ignoring

When to use

You are seeing this: An invoice payment attempt failed: declined card, soft decline, or no payment method on file. Use this skill when you run into "Stripe event: invoice.payment_failed, start dunning, the subscription is not dead yet".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

invoice.payment_failed: run your dunning playbook

An invoice payment attempt failed: declined card, soft decline, or no payment method on file. The subscription is now past_due, not canceled. There is still time.

What to do on receipt

1. Read attempt_count and next_payment_attempt on the invoice. If Stripe will retry soon on its own, your first email can be gentle: "we'll try again, or update your card now."
2. Email the customer with a link to update their payment method. Make it one click. Every extra step here costs you the subscription.
3. Track dunning state yourself: how many failures for this invoice, when the last reminder went out. Escalate the tone as attempts climb.
4. If the customer updates the method, you can retry the invoice immediately via the API instead of waiting for the next automatic attempt.
5. Return 200.

The trap

Treating this as terminal and deprovisioning. past_due still has access in most setups; killing the account on the first failed renewal manufactures the churn you were trying to avoid. The other trap: ignoring next_payment_attempt and emailing "final notice" language before Stripe has even retried once.

Checklist

• Smart Retries and your retry settings in the Dashboard decide the automatic schedule. Your handler should read next_payment_attempt rather than assuming a cadence.
• After the final failed attempt, the subscription moves to canceled or unpaid per your settings, and you get customer.subscription.deleted. That is when deprovisioning happens, not here.

Stripe's event reference says invoice.paymentfailed occurs whenever an invoice payment attempt fails, due to either a declined payment, including soft decline, or to the lack of a stored payment method. Verified live at https://docs.stripe.com/api/events/types. attemptcount and nextpaymentattempt on the Invoice object are the documented dunning fields.