invoice.payment_action_required Stripe Webhook — Shopify Subscription Fix
Root cause
Stripe fires the invoice.payment_action_required webhook event when a subscription invoice payment results in a PaymentIntent with status requires_action. This means the card issuer requires 3D Secure authentication before the charge can complete. The invoice remains open and unpaid. Unlike a simple card decline, requires_action is recoverable if the customer completes the authentication challenge — but completing it requires the customer to visit a specific URL, which Stripe provides in the PaymentIntent's next_action field.
Symptoms
- • Stripe webhook event: invoice.payment_action_required received in your endpoint
- • Stripe PaymentIntent status: requires_action
- • Stripe invoice status: open — payment not collected
- • Shopify billing attempt may show errorCode: AUTHENTICATION_REQUIRED
- • Customer receives no authentication prompt unless your system sends one
How to fix it
Listen for invoice.payment_action_required in your webhook handler
In your Stripe webhook endpoint, add a handler for the invoice.payment_action_required event type. This is distinct from invoice.payment_failed — it means the charge requires customer action, not that it failed permanently. Register the webhook in Stripe Dashboard > Developers > Webhooks.
Open in admin →Extract the 3DS confirmation URL from the webhook payload
In the invoice.payment_action_required webhook payload, find the payment_intent object. Within it, access next_action.redirect_to_url.url — this is the 3DS authentication URL the customer must visit. This URL is time-limited; extract and send it to the customer promptly.
Email customer the 3DS confirmation URL
Send the customer an email with the next_action.redirect_to_url value as a clear call-to-action button. Use a subject line like 'Action required: confirm your subscription payment.' The URL expires — give the customer 48–72 hours to respond. Do not retry the payment while waiting for authentication.
Handle invoice.payment_succeeded after customer completes 3DS
After the customer completes authentication, Stripe fires invoice.payment_succeeded. In your webhook handler, update the subscription state in Recharge or your system to reflect successful payment. If Shopify billing attempt was pending, verify it is marked as successful. Resume normal subscription billing.
Frequently asked questions
What is the difference between invoice.payment_failed and invoice.payment_action_required?
invoice.payment_failed means Stripe attempted the charge and the card issuer declined it — no customer action will change the outcome without a new payment method or retry timing. invoice.payment_action_required means the charge is pending customer authentication — the charge can succeed once the customer completes the 3DS challenge.
Does Shopify automatically handle invoice.payment_action_required for subscriptions?
No. Shopify's subscription billing layer does not automatically send customers a 3DS confirmation link when authentication is required. The merchant is responsible for listening to the Stripe webhook, extracting the authentication URL, and delivering it to the customer. Without this, the subscription renewal is stuck indefinitely.
How long does the customer have to complete the 3DS authentication?
The next_action.redirect_to_url from Stripe is typically valid for several hours to a few days, depending on the issuer. Stripe's invoice will remain open during this window. After the URL expires, the invoice typically moves to uncollectible. Send the authentication email promptly and follow up if the customer does not complete it within 24 hours.
What happens if the customer ignores the authentication email?
If the customer does not complete 3DS authentication before the URL expires, the Stripe invoice moves to uncollectible status and the subscription payment fails permanently for that cycle. The subscription may continue to the next billing cycle and attempt again — potentially triggering another authentication requirement.
Detect this error automatically
Free cross-stack scan finds all billing errors in 60 seconds.
Run Free Scan →