Supporting 3D Secure Authentication on Web

    Learn how to perform additional authentication with your Checkout or Stripe.js integration.

    Incorporating 3D Secure authentication into your integration

    Stripe’s new Checkout and the Payment Intents API natively support 3D Secure and trigger it automatically if required by a regulatory mandate such as Strong Customer Authentication. You can also use Radar rules to control when customers are prompted to complete 3D Secure authentication, making a determination for each user based on the desired parameters.

    On the web, you have a few options for displaying 3D Secure:

    • Checkout: Checkout automatically triggers 3D Secure in a modal when required without any additional work from you.
    • Pre-built modal: The Payment Intents API integrates tightly with Stripe.js and Elements to simplify the authentication process. If your Stripe integration uses handleCardPayment, handleCardAction or handleCardSetup, Stripe.js automatically handles the authentication process—displaying a modal dialog where the customer can provide the requisite information.
    • Full-page redirect: You can send the customer to complete authentication via a full-page redirect by manually handling 3D Secure authentication instead of using the pre-built modal.
    • Customized UI: You can customize how and where the 3D Secure UI is shown with our guide.

    With the iOS and Android Payment Intents API integrations, you can add a native, customizable 3D Secure integration in your app. See our iOS and Android guides on supporting 3D Secure in your app.

    To track whether 3D Secure was attempted on a card payment, you can read the three_d_secure property on the card information in the charge’s payment_method_details. The property is populated when 3D Secure is attempted on a charge, and three_d_secure.succeeded indicates whether 3DS authentication was successful.

    Triggering Dynamic 3D Secure authentication with Radar rules

    3D Secure is automatically triggered if required by a regulatory mandate such as Strong Customer Authentication.

    In addition, Stripe provides three default rules to dynamically request 3D Secure when using the new version of Checkout or the Payment Intents API. You can configure these 3D Secure Radar rules in your Stripe Dashboard. The following screenshot depicts these Radar rules, which request additional authentication from customers when the issuer of their card requires 3D Secure:

    The first two rules are enabled by default. You can disable the default rules if you do not wish to apply them.

    If you have Radar for Fraud Teams, you can add custom 3D Secure rules using the syntax described in our Rules reference. Radar requests 3D Secure authentication for payments that match these rules. In the example below, the enabled rule requests 3D Secure authentication for payment attempts where the amount of the payment exceeds $500 USD and the risk level is not considered normal.

    Manually requesting 3D Secure with custom logic

    The simplest way to request 3D Secure is using Radar to dynamically request 3D Secure based on risk level and other requirements. However, you can also request 3D Secure based on logic from your own fraud engine.

    To request 3D Secure for one-time payments or future off-session payments, the process is the same. Supply the request_three_d_secure parameter in the card payment_method_options when creating or confirming a PaymentIntent or SetupIntent. When the parameter is provided, Stripe attempts to perform 3D Secure. This overrides any dynamic 3D Secure Radar rules on the PaymentIntent or SetupIntent.

    When to provide payment_method_options[card][request_three_d_secure]='any' depends on when your fraud engine detects risk. For example, if your fraud engine only inspects card details, you know whether to request 3D Secure before you create the PaymentIntent or SetupIntent. If your fraud engine inspects both card and transaction details, provide the parameter during confirmation—once you have more information. Then pass the resulting PaymentIntent or SetupIntent to your client to complete the process.

    Explore the request_three_d_secure parameter’s usage for each case in the API reference:

    Whenever 3D Secure authentication is available for a card, Stripe requires your customer to perform authentication to complete the payment successfully. If 3D Secure is not available for the given card, the payment proceeds normally.

    Stripe’s SCA rules run automatically, regardless of whether you manually request 3D Secure. Any 3D Secure prompts from you are additional and not required for SCA compliance.

    Testing 3D Secure payments

    Not all cards support 3D Secure or require the customer be redirected to their card issuer’s authentication page. Use the following card information to fully test 3D Secure payments.

    Number 3D Secure usage Description
    4000000000003220 Required 3D Secure 2 authentication must be completed for the payment to be successful. By default, your Radar rules will request 3D Secure authentication for this card.
    4000000000003063 Required 3D Secure authentication must be completed for the payment to be successful. By default, your Radar rules will request 3D Secure authentication for this card.
    4000008400001629 Required 3D Secure authentication is required, but payments will be declined with a card_declined failure code after authentication. By default, your Radar rules will request 3D Secure authentication for this card.
    4000000000003055 Supported 3D Secure authentication may still be performed, but is not required. By default, your Radar rules will not request 3D Secure authentication for this card.
    4242424242424242 Supported 3D Secure is supported for this card, but this card is not enrolled in 3D Secure. This means that if 3D Secure is requested by your Radar rules, the customer will not go through additional authentication. By default, your Radar rules will not request 3D Secure authentication for this card.
    378282246310005 Not supported 3D Secure is not supported on this card and cannot be invoked. The PaymentIntent will proceed without performing authentication.
    Token 3D Secure usage Description
    tok_threeDSecure2Required Required 3D Secure 2 authentication must be completed for the payment to be successful. By default, your Radar rules will request 3D Secure authentication for this card.
    tok_threeDSecureRequired Required 3D Secure authentication must be completed for the payment to be successful. By default, your Radar rules will request 3D Secure authentication for this card.
    tok_threeDSecureRequiredChargeDeclined Required 3D Secure authentication is required, but payments will be declined with a card_declined failure code after authentication. By default, your Radar rules will request 3D Secure authentication for this card.
    tok_threeDSecureOptional Supported 3D Secure authentication may still be performed, but is not required. By default, your Radar rules will not request 3D Secure authentication for this card.
    tok_visa Supported 3D Secure is supported for this card, but this card is not enrolled in 3D Secure. This means that if 3D Secure is requested by your Radar rules, the customer will not go through additional authentication. By default, your Radar rules will not request 3D Secure authentication for this card.
    tok_amex_threeDSecureNotSupported Not supported 3D Secure is not supported on this card and cannot be invoked. The PaymentIntent will proceed without performing authentication.
    Payment Method 3D Secure usage Description
    pm_card_threeDSecure2Required Required 3D Secure 2 authentication must be completed for the payment to be successful. By default, your Radar rules will request 3D Secure authentication for this card.
    pm_card_threeDSecureRequired Required 3D Secure authentication must be completed for the payment to be successful. By default, your Radar rules will request 3D Secure authentication for this card.
    pm_card_threeDSecureRequiredChargeDeclined Required 3D Secure authentication is required, but payments will be declined with a card_declined failure code after authentication. By default, your Radar rules will request 3D Secure authentication for this card.
    pm_card_threeDSecureOptional Supported 3D Secure authentication may still be performed, but is not required. By default, your Radar rules will not request 3D Secure authentication for this card.
    pm_card_visa Supported 3D Secure is supported for this card, but this card is not enrolled in 3D Secure. This means that if 3D Secure is requested by your Radar rules, the customer will not go through additional authentication. By default, your Radar rules will not request 3D Secure authentication for this card.
    pm_card_amex_threeDSecureNotSupported Not supported 3D Secure is not supported on this card and cannot be invoked. The PaymentIntent will proceed without performing authentication.

    All other Visa and Mastercard test cards do not require authentication from the customer’s card issuer.

    Testing the authentication process

    When you build an integration with your test API keys, the authentication process displays a modal with information about the API request. In that dialog, you can either authorize or cancel the payment. Authorizing the payment simulates successful authentication and redirects you to the specified return URL. Clicking on the Failure button simulates an unsuccessful attempt at authentication.

    You can write custom Radar rules in test mode to trigger authentication on test cards. You can learn more about testing your Radar rules in our Radar documentation.

    Next steps

    Congratulations, you have learned about 3D Secure and performing Dynamic 3D Secure authentication with Radar. For more information, refer to the following documentation:

    Was this page helpful? Yes No

    Send

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    On this page