Detect a 3DS challenge requirement: when confirming a PaymentIntent, a status of 'requires_action' with next_action.type 'use_stripe_sdk' or 'redirect_to_url' means the card issuer requires authentication — surface this to the user immediately.
On the client, call stripe.handleNextAction() (Stripe.js) or equivalent mobile SDK method to present the 3DS challenge iframe or redirect; on completion the PaymentIntent status transitions to 'requires_confirmation' or directly to 'succeeded'.
If authentication fails, the PaymentIntent moves to 'requires_payment_method' with last_payment_error.code 'authentication_required' — do not retry the same PaymentIntent; instead detach the failed method and prompt the user to re-enter payment details.
For off-session recurring charges that fail with 'authentication_required', send the customer an email with a link to a hosted payment page (use Stripe's hosted invoice or a custom page) where they can complete the 3DS challenge on-session.
Use Smart Retries (enabled by default on subscriptions) for soft declines, but for hard authentication failures always require explicit customer action rather than automatic retry.
Log 'last_payment_error.decline_code' and 'last_payment_error.payment_method.card.three_d_secure_usage.supported' to distinguish cards that never support 3DS (and may need exemption requests) from transient failures.
Known gotchas
Retrying an off-session charge without SCA when the card requires it will result in a 'authentication_required' decline from the issuer; passing 'off_session=true' only works for genuinely merchant-initiated transactions with a properly stored and consented mandate.
In European Economic Area under PSD2, exemptions (low-value, TRA, MIT) must be requested at confirmation time; they can be declined by the issuer, so always have a fallback on-session flow.
PaymentIntents in 'requires_action' status expire after roughly one hour; if the user does not complete 3DS within that window, the intent must be recreated.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?