Authenticate with 3D Secure

You can integrate 3D Secure (3DS) authentication into your checkout flow on multiple platforms, including Web, iOS, Android, and React Native. This integration runs 3D Secure 2 (3DS2) when supported by the customer’s bank and falls back to 3D Secure 1 otherwise. To use Stripe’s 3DS service with other processors, contact support.

Web

iOS

Android

The customer enters their card details.

The SDK presents a loading screen while the customer’s bank checks whether authentication is required.

If required by their bank, the SDK authenticates the customer.

Control the 3DS flow

Stripe automatically triggers 3DS when required by regulations such as Strong Customer Authentication in Europe, industry guidelines such as the Credit Card Security Guidelines in Japan, if requested by an issuer with a soft decline code, or when certain Stripe optimizations apply.

You can also use Radar rules or the API to control when to prompt users to complete 3DS authentication, making a determination for each user based on the desired parameters. However, not all transactions support 3DS, for example wallets or off-session payments.

When a payment triggers 3DS, Stripe requires the user to perform authentication to complete the payment if 3DS authentication is available for a card. Depending on what frontend you use, this might require you to display the 3DS Flow.

In a typical Payment Intent API flow that triggers 3DS:

1. The user enters their payment information, which confirms a PaymentIntent, SetupIntent, or attaches a PaymentMethod to a Customer.
2. Stripe assesses if the transaction supports and requires 3DS based on regulatory mandates, Radar rules, manual API requests, issuer soft declines, and other criteria.
3. If 3DS is:
   • Not required: For example, because of an exemption, Stripe attempts the charge. The PaymentIntent transitions to a status of processing. If requested by the issuer with a soft decline, we automatically reattempt and continue as if required.
   • Not supported: The PaymentIntent transitions to a status of requires_payment_method. Depending on the reason 3DS was triggered it might be permissible to continue to the authorization step for the charge. In that case, the PaymentIntent transitions to a status of processing.
   • Required: Stripe starts the 3DS authentication flow by contacting the card issuer’s 3D Secure Access Control Server (ACS) and starting the 3DS flow.
4. When Stripe receives 3DS flow information from the issuer, we attempt authentication. The PaymentIntent transitions to a status of requires_action:
   • See below for how to display the required 3DS action. Issuers might request different 3DS flow action types, which might not always result in visibly displaying a 3DS challenge (for example, a frictionless flow).
   • If the issuer doesn’t support 3DS at all or has an outage, Stripe might attempt to complete the payment without authentication if permissible.
   • Data for 3DS authentication requests is typically provided by the customer at the time of the transaction. To reduce friction and the possibility of failed authentication, we might complete these requests with data we infer from other sources such as data collected from your customer during the payment flow, records related to your customer’s past transactions with you, or relevant information available from the customer’s card or issuers.
   • If Stripe already has access to all the required 3DS data elements, our optimized 3DS server might attempt to complete the authentication request for you while confirming the PaymentIntent. This can result in the PaymentIntent directly transitioning to a status of processing if the 3DS flow succeeds, or to a status of requires_action if additional steps or data elements are required to complete the 3DS flow.
5. Depending on the 3DS authentication result:
   • Authenticated: Stripe attempts the charge and the PaymentIntent transitions to a status of processing.
   • Failure: The PaymentIntent transitions to a status of requires_payment_method, indicating that you need to try a different payment method, or you can retry 3DS by reconfirming.
   • Other scenarios: Depending on the reason the payment triggered 3DS, it might be permissible to continue authorization for the charge in edge cases. For example, a result of attempt_acknowledged leads to a charge and the PaymentIntent transitions to a status of processing.
     • An exception is when creating Indian e-mandates for recurring payments. Anything but an authenticated result is treated as failure.
6. The PaymentIntent transitions to one of the following statuses, depending on the outcome of the payment: succeeded, requires_capture, or requires_payment_method.

To track whether 3DS was supported and attempted on a card payment, read the three_d_secure property on the card information in the Charge’s payment_method_details. Stripe populates the three_d_secure property when the customer attempts to authenticate the card—three_d_secure.result indicates the authentication outcome.

Use Radar rules in the Dashboard

Stripe provides default Radar rules to dynamically request 3DS when creating or confirming a PaymentIntent or SetupIntent. You can configure these rules in your Dashboard.

If you have Radar for Fraud Teams, you can add custom 3DS rules.

Manually request 3DS with the API

The default method to trigger 3DS is using Radar to dynamically request 3D Secure based on risk level and other requirements. Triggering 3DS manually is for advanced users integrating Stripe with their own fraud engine.

To trigger 3DS manually, set payment_method_options[card][request_three_d_secure] to any or challenge depending on what you want to optimize for when either creating or confirming a PaymentIntent or SetupIntent, or creating a Checkout Session. This process is the same for one-time payments or when setting up a payment method for future payments. When you provide this parameter, Stripe attempts to perform 3DS and overrides any dynamic 3D Secure Radar rules on the PaymentIntent, SetupIntent, or Checkout Session.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_options[card][request_three_d_secure]"=any

When to provide this parameter depends on when your fraud engine detects risk. For example, if your fraud engine only inspects card details, you know whether to request 3DS before you create the PaymentIntent or SetupIntent. If your fraud engine inspects both card and transaction details, provide the parameter during confirmation—when 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:

• Create a PaymentIntent
• Confirm a PaymentIntent
• Create a SetupIntent
• Confirm a SetupIntent
• Create a Checkout Session

Set request_three_d_secure to any to manually request 3DS with a preference for a frictionless flow, increasing the likelihood of the authentication being completed without any additional input from the customer.

Set request_three_d_secure to challenge to request 3DS with a preference for a challenge flow, where the customer must respond to a prompt for active authentication.

Stripe can’t guarantee your preference because the issuer determines the ultimate authentication flow. You can find out what the ultimate authentication flow was by inspecting the authentication_flow on the three_d_secure property of the Charge or SetupAttempt. To learn more about 3DS flows, read our guide.

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

Display the 3DS flow

Web

iOS

Android

React Native

Note

PaymentSheet and PaymentSheet.FlowController automatically support 3DS authentication. If you’re using one of these classes, this guide doesn’t apply.

The STPPaymentHandler class presents UIViewControllers over your app for authentication. STPPaymentHandler.threeDSCustomizationSettings contains the customizable items for 3DS authentication.

The authenticationTimeout property controls how long the 3DS authentication process runs before it times out. This duration includes both network round trips and awaiting customer input, and must be at least 5 minutes. If authentication times out, STPPaymentHandler reports an error with code STPPaymentHandlerTimedOutErrorCode in the completion block.

The uiCustomization property allows you to provide a STPThreeDSUICustomization instance to control the look and feel of the authentication UI. For each customizable element of the UI, such as the navigation bar or the Submit button, there’s a corresponding class with properties to configure colors, fonts, text, borders, and so on. See the STPThreeDSUICustomization documentation for a detailed explanation of each parameter.

The Stripe iOS SDK collects basic device information during 3DS2 authentication and sends it to the issuing bank for their risk analysis.

The following example code demonstrates some of the configuration for a dark UI color theme.

Swift

let uiCustomization = STPPaymentHandler.shared().threeDSCustomizationSettings.uiCustomization
      uiCustomization.textFieldCustomization.keyboardAppearance = .dark
      uiCustomization.navigationBarCustomization.barStyle = .black
      uiCustomization.navigationBarCustomization.textColor = .white
      uiCustomization.buttonCustomization(for: .cancel).textColor = .white

You have four different types of challenge screens that you can present to your customer. Test your UI customization with these different screens with your customization.

You can also configure which view controller presents the authentication UI and other behavior using the STPAuthenticationContext passed to STPPaymentHandler.

Set up a return URL

The iOS SDK can present a webview in your app to authenticate your customer instead of a native view (for example, if your customer is using an outdated app version). When authentication finishes, the webview can automatically dismiss itself instead of having your customer close it. To enable this behavior, configure a custom URL scheme or universal link and set up your app delegate to forward the URL to the SDK.

Swift

// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (stripeHandled) {
        return true
    } else {
        // This was not a Stripe url – handle the URL normally as you would
    }
    return false
}

// This method handles opening universal link URLs (for example, "https://example.com/stripe_ios_callback")
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
        if let url = userActivity.webpageURL {
            let stripeHandled = StripeAPI.handleURLCallback(with: url)
            if (stripeHandled) {
                return true
            } else {
                // This was not a Stripe url – handle the URL normally as you would
            }
        }
    }
    return false
}

Next, pass the URL as the return_url when you confirm the PaymentIntent (if you’re collecting a payment) or SetupIntent (if you’re saving card details). After webview-based authentication finishes, Stripe redirects the user back to your app or web page with the return_url you provided.

Test the 3DS flow

Use a Stripe test card with any CVC, postal code, and future expiration date to trigger 3DS authentication challenge flows while in a sandbox.

When you build an integration with your test API keys, the authentication process displays a mock authentication page. On that page, you can either authorize or cancel the payment. Authorizing the payment simulates successful authentication and redirects you to the specified return URL. Clicking the Failure button simulates an unsuccessful attempt at authentication.

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

You can write custom Radar rules in a test environment to trigger authentication on test cards. Learn more about testing your Radar rules.

Disputes and liability shift

The liability shift rule applies to payments successfully authenticated using 3D Secure. In some cases, liability shift applies with equivalent cryptograms, such as Apple Pay or Google Pay. If a cardholder disputes a 3DS payment as fraudulent, the liability typically shifts from you to the card issuer.

If a card doesn’t support 3DS or an error occurs during the authentication process, the payment proceeds normally. When this occurs, liability doesn’t generally shift to the issuer, because a successful 3DS authentication hasn’t taken place.

In practice, this means you typically won’t receive disputes marked as fraudulent if the payment is covered by the liability shift rule, but you might still receive an Early Fraud Warning. You might still receive a low percentage of fraudulent disputes, and we list a few cases below where the liability shift rule might not apply.

You might receive a dispute inquiry on a successfully authenticated payment using 3DS. This type of dispute doesn’t precipitate a chargeback because it’s only a request for information.

If you receive an inquiry for a 3D-Secure-authenticated charge, you must respond. If you don’t, the cardholder’s bank can initiate a financial chargeback known as a “no-reply” chargeback that could invalidate the liability shift. To prevent no-reply chargebacks on 3DS charges, submit sufficient information about the charge. Include information about what was ordered, how it was delivered, and who it was delivered to (whether it was physical or electronic goods, or services).

Liability shift might also occur when the card network requires 3DS, but it isn’t available for the card or issuer. This can happen if the issuer’s 3DS server is down or if the issuer doesn’t support it, despite the card network requiring support. During the payment process, the cardholder isn’t prompted to complete 3DS authentication, because the card isn’t enrolled. Although the cardholder didn’t complete 3DS authentication, liability can still shift to the issuer.

Stripe returns the requested Electronic Commerce Indicator (ECI) in the electronic_commerce_indicator of the 3DS authentication outcome. This indicator can aid in determining whether a charge should adhere to the liability shift rule. As 3DS occurs subsequent to the initial payment intent response, you typically get this from a charge.succeeded event that’s sent to one of your configured webhook endpoints or other event destinations. A requested ECI might be degraded in the issuer response, which we don’t reveal.

Sometimes payments that are successfully authenticated using 3DS don’t fall under liability shift. This is rare and can happen, for example, if you have an excessive level of fraud on your account and are enrolled in a fraud monitoring program. Certain networks have also exempted some industries from liability shift. For example, Visa doesn’t support liability shift for businesses engaging in wire transfer or money orders, non-financial institutions offering foreign or non-fiat currency, or stored-value card purchase or load.

In rare cases, liability shift might get downgraded post-authorization, or the card networks’ dispute rejection system might fail to catch liability shift for a transaction. In these cases, if you counter the dispute, Stripe automatically adds the requested ECI and the 3DS authentication outcome for the payment to your evidence details, but we encourage you to include additional details to improve your odds of winning the dispute.

Custom Radar rules for 3DS and liability shift

If you have Radar for Fraud Teams, you can customize your rules to control when to request 3DS and how to handle each specific authentication outcome and liability shift. Stripe’s Strong Customer Authentication (SCA) rules run automatically and independently of custom Radar rules, and block unauthenticated payments unless exempted.