How 3D Secure (3DS) works with subscription payments

When a customer's card uses 3D Secure, Lago handles it as part of normal subscription billing. The subscription is created right away, and when the cardholder needs to authenticate a payment, Lago signals that through a webhook so your application can complete it. Nothing about 3DS prevents the subscription from being created, and a payment that is waiting on authentication is expected behavior rather than a failure.

Optional pre-authorization

Pre-authorization is an opt-in step. It runs only when the subscription request includes an authorization parameter and the account has the payment authorization beta enabled. When it runs, Lago places a temporary hold on the card and releases it immediately. 3DS cards are handled gracefully here: Lago completes pre-authorization and creates the subscription, and authentication is simply carried out at invoice payment instead. This behavior is a beta implementation detail and may change.

What to expect at payment

Payment is taken when the subscription invoice is finalized. For a 3DS card, Stripe asks the cardholder to authenticate before the charge can go through. Because authentication needs the cardholder, Lago marks the invoice as pending and emits a payment.requires_action webhook so your application knows to prompt them. The subscription stays active throughout. A pending invoice in this situation does not mean anything is broken; it means the payment is waiting on the cardholder to complete authentication. In Stripe, the matching PaymentIntent shows requires_action with an authentication_required reason while it waits.

Completing authentication

Authentication is completed on the client side using Stripe's standard SCA flow. When you receive the payment.requires_action webhook, present the challenge to the customer in the browser with Stripe.js, using stripe.handleCardAction() or stripe.confirmCardPayment(). Stripe's 3D Secure and SCA documentation covers the client-side handling in full. The subscription already exists, so once authentication succeeds there is nothing further to create on the Lago side.

If the customer authenticated earlier through a SetupIntent, that authentication can be reused for later charges within the authentication window. For recurring charges you can also request a 3DS exemption from Stripe, though the cardholder's bank makes the final decision on whether to grant it.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.