There are three ways to display the 3D Secure flow on web:

• Show the authentication UI in a pop-up modal (default behavior when calling confirmCardPayment and handleCardAction)
• Redirect to the bank’s website
• Use an iframe

Redirect to the bank website

To redirect your customer to the 3DS authentication page, pass a return_url to the PaymentIntent when confirming on the server or on the client. You can also set return_url when creating the PaymentIntent.

After confirmation, if a PaymentIntent has a requires_action status, inspect the PaymentIntent’s next_action. If it’s redirect_to_url, that means 3D Secure is required.

next_action: {
    type: 'redirect_to_url',
    redirect_to_url: {
      url: 'https://hooks.stripe.com/...',
      return_url: 'https://mysite.com'
    }
}

In the browser, redirect the customer to the url in the redirect_to_url hash to complete authentication.

var action = intent.next_action;
if (action && action.type === 'redirect_to_url') {
  window.location = action.redirect_to_url.url;
}

When the customer finishes the authentication process, the redirect sends them back to the return_url you specified when you created or confirmed the PaymentIntent. The redirect also adds payment_intent and payment_intent_client_secret URL query parameters that your application can use to identify the PaymentIntent associated with the customer’s purchase.

Display in an iframe

You cannot customize the authentication UI on the web to match your website’s design—the bank that issued the card controls the fonts and colors of the experience.

However, you can choose how and where the 3D Secure UI is shown. Most merchants show it in a modal dialog above their payment page. If you have your own modal component, you can place the 3D Secure frame inside of it. You can also show the authentication content inline with your payment form.

stripe.confirmCardPayment(
  '{{PAYMENT_INTENT_CLIENT_SECRET}}',
  {
    payment_method: {card: cardElement},
    return_url: 'https://example.com/return_url'
  },
  // Disable the default next action handling.
  {handleActions: false}
).then(function(result) {
  // Handle result.error or result.paymentIntent
  // More details in Step 2.
});

curl https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/confirm \
-u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
-d return_url="https://example.com/return_url"

intent = Stripe::PaymentIntent.confirm(
  '{{PAYMENT_INTENT_ID}}',
  {
    return_url: 'https://example.com/return_url',
  }
)

intent = stripe.PaymentIntent.confirm(
  '{{PAYMENT_INTENT_ID}}',
  return_url='https://example.com/return_url'
)

$intent = \Stripe\PaymentIntent::retrieve('{{PAYMENT_INTENT_ID}}');
$intent->confirm([
  'return_url' => 'https://example.com/return_url',
]);

PaymentIntent intent = PaymentIntent.retrieve("{{PAYMENT_INTENT_ID}}");
Map<String, Object> params = new HashMap<String, Object>();
params.put("return_url", "https://example.com/return_url");
intent.confirm(params);

const intent = await stripe.paymentIntents.confirm('{{PAYMENT_INTENT_ID}}', {
  return_url: 'https://example.com/return_url',
});

params := &stripe.PaymentIntentConfirmParams{
  ReturnUrl: stripe.String("https://example.com/return_url"),
}
intent, err := paymentintent.Confirm("{{PAYMENT_INTENT_ID}}", params)

var service = new PaymentIntentService();
var options = new PaymentIntentConfirmOptions
{
  ReturnUrl = "https://example.com/return_url",
};
var intent = service.Confirm("{{PAYMENT_INTENT_ID}}", options);

var iframe = document.createElement('iframe');
iframe.src = paymentIntent.next_action.redirect_to_url.url;
iframe.width = 600;
iframe.height = 400;
yourContainer.appendChild(iframe);

window.top.postMessage('3DS-authentication-complete');

function on3DSComplete() {
  // Hide the 3DS UI
  yourContainer.remove();

  // Check the PaymentIntent
  stripe.retrievePaymentIntent('{{PAYMENT_INTENT_CLIENT_SECRET}}')
    .then(function(result) {
      if (result.error) {
        // PaymentIntent client secret was invalid
      } else {
        if (result.paymentIntent.status === 'succeeded') {
          // Show your customer that the payment has succeeded
        } else if (result.paymentIntent.status === 'requires_payment_method') {
          // Authentication failed, prompt the customer to enter another payment method
        }
      }
    });
}

window.addEventListener('message', function(ev) {
  if (ev.data === '3DS-authentication-complete') {
    on3DSComplete();
  }
}, false);

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

The authenticationTimeout property controls how long the 3D Secure authentication process will run 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 will report 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, like the navigation bar or the Submit button, there is a corresponding class with properties to configure colors, fonts, text, borders, etc. See the STPThreeDSUICustomization documentation for a detailed explanation of each parameter.

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

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

STPThreeDSUICustomization *uiCustomization = [STPPaymentHandler sharedHandler].threeDSCustomizationSettings.uiCustomization;
uiCustomization.textFieldCustomization.keyboardAppearance = UIKeyboardAppearanceDark;
uiCustomization.navigationBarCustomization.barStyle = UIBarStyleBlack;
uiCustomization.navigationBarCustomization.textColor = UIColor.whiteColor;
[uiCustomization buttonCustomizationForButtonType:STPThreeDSCustomizationButtonTypeCancel].textColor = UIColor.whiteColor;

There are four different types of challenge screens that may be presented 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 via 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 is finished, 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.

// This method handles opening custom URL schemes (e.g., "your-app://")
func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
    let stripeHandled = Stripe.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 (e.g., "https://example.com/stripe_ios_callback")
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
        if let url = userActivity.webpageURL {
            let stripeHandled = Stripe.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 custom URL schemes (e.g., "your-app://")
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    BOOL stripeHandled = [Stripe handleStripeURLCallbackWithURL:url];
    if (stripeHandled) {
        return YES;
    } else {
        // This was not a Stripe url – handle the URL normally as you would
    }
    return NO;
}

// This method handles opening universal link URLs (e.g., "https://example.com/stripe_ios_callback")
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
    if (userActivity.activityType == NSUserActivityTypeBrowsingWeb) {
        if (userActivity.webpageURL) {
            BOOL stripeHandled = [Stripe handleStripeURLCallbackWithURL:userActivity.webpageURL];
            if (stripeHandled) {
                return YES;
            } else {
                // This was not a Stripe url – handle the URL normally as you would
            }
            return NO;
        }
    }
    return NO;
}

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 is finished, Stripe redirects the user back to your app or web page with the return_url you provided.

PaymentAuthConfig.Stripe3ds2Config contains the customizable items for 3D Secure authentication interactions.

The timeout property controls how long the 3D Secure authentication process runs before it times out. This duration includes both network round trips and awaiting customer input. Note that this value must be at least 5 minutes in order to remain compliant with Strong Customer Authentication regulation. A value less than 5 minutes results in an error.

The uiCustomization property allows you to provide a StripeUiCustomization instance to control the look of views presented by the Android SDK during 3D Secure authentication. Stripe currently supports customization parameters for colors, fonts, text, borders on app bars, labels, text fields, and buttons. See the SDK documentation for a full explanation of each parameter.

final PaymentAuthConfig.Stripe3ds2UiCustomization uiCustomization =
        new PaymentAuthConfig.Stripe3ds2UiCustomization.Builder()
                .setLabelCustomization(
                        new PaymentAuthConfig.Stripe3ds2LabelCustomization.Builder()
                                .setTextFontSize(12)
                                .build())
                .build();
PaymentAuthConfig.init(new PaymentAuthConfig.Builder()
        .set3ds2Config(new PaymentAuthConfig.Stripe3ds2Config.Builder()
                .setTimeout(5)
                .setUiCustomization(uiCustomization)
                .build())
        .build());

val uiCustomization = PaymentAuthConfig.Stripe3ds2UiCustomization.Builder()
    .setLabelCustomization(
        PaymentAuthConfig.Stripe3ds2LabelCustomization.Builder()
            .setTextFontSize(12)
            .build()
    )
    .build()
PaymentAuthConfig.init(
    PaymentAuthConfig.Builder()
        .set3ds2Config(
            PaymentAuthConfig.Stripe3ds2Config.Builder()
                .setTimeout(5)
                .setUiCustomization(uiCustomization)
                .build()
        )
        .build()
)

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

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

When testing your custom iOS integration, pick a test card to trigger a specific challenge flow.

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

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

When testing your custom Android integration, pick a test card to trigger a specific challenge flow.

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

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