Supporting 3D Secure Authentication on Android

    Learn about how to use the Android SDK to perform additional required authentication.

    Supporting additional authentication in your app requires the Payment Intents API or Setup Intents API. The Android SDK supports both native and web-redirect authentication, and manages presenting any required screens to your customer. After authentication has completed, the result (e.g., succeeded, canceled, or failed) is reported back to your app.

    Manual handling of redirects is still supported, but we recommend following this guide to support native 3D Secure authentication.

    3D Secure authentication

    The Android SDK allows your app to perform 3D Secure authentication without redirecting to a browser. The SDK entry points into the 3D Secure authentication flow are Stripe#confirmPayment() and Stripe#authenticatePayment() for Payment Intents, and Stripe#confirmSetupIntent() and Stripe#authenticateSetup() for Setup Intents. Additionally, PaymentAuthConfig provides options to customize the 3D Secure authentication experience for your users.

    In the 3D Secure authentication flow, the Android SDK presents a loading screen modal over your Activity that starts the authentication flow. Depending on whether additional customer interaction is required, the Android SDK will either dismiss the loading screen or present additional screens to collect more information. When the 3D Secure authentication process has completed, timed out, or canceled by the customer, the Android SDK will finish any presented Activity and return the result through Activity#onActivityResult().

    Example of a 3D Secure 2 flow

    Checkout screen

    Step 1: The customer enters their payment information.

    Initiate authentication

    Step 2: The customer’s bank assesses the transaction and requires 3D Secure.

    Challenge flow screen

    Step 3: The customer completes the additional authentication step.

    Customizing

    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()
    )

    There are 4 different types of challenge screens that may be presented to your customer. Test your UI customization with these different screens.

    Testing

    It’s important to thoroughly test your 3D secure integration and any customization you’ve applied to make sure you’re correctly handling cards that require additional authentication. Use these card numbers in test mode with any expiration date in the future and any three digit CVC code to trigger the different challenge screens that may be shown and validate your integration.

    Number Challenge Flow Description
    4000000000003220 Out of Band 3D Secure 2 authentication must be completed on all transactions. Triggers the challenge flow with Out of Band UI.
    4000000000003238 One Time Passcode 3D Secure 2 authentication must be completed on all transactions. Triggers the challenge flow with One Time Passcode UI.
    4000000000003246 Single Select 3D Secure 2 authentication must be completed on all transactions. Triggers the challenge flow with single-select UI.
    4000000000003253 Multi Select 3D Secure 2 authentication must be completed on all transactions. Triggers the challenge flow with multi-select UI.

    Use these cards in your application or the Emoji Apparel Store app to test the different 3D Secure challenge flows.

    Was this page helpful?

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

    On this page