Use D1 SDK authentication

Let the D1 SDK manage Android device authentication during payment.

Overview

In this model, the issuer application starts authentication by calling the D1 SDK authentication API.

The D1 SDK then displays and manages the Android device authentication prompt.

The issuer application still manages the surrounding payment UX. It should show transaction progress, guide the end user, and handle success and error states.

Flow

Implement ContactlessTransactionListener::onAuthenticationRequired() and call startAuthenticate() with an AuthenticationParameter.

Provide the activity context and the strings shown in the authentication prompt.

The D1 SDK manages the Android device authentication screen.

Do not start a separate Android device authentication flow in parallel.

For devices running earlier than Android Q (API level 29), Android does not provide the system fingerprint prompt. On those devices, implement your own fingerprint UI before calling startAuthenticate(). We recommend always showing an authentication UI and then calling startAuthenticate(). On Android Q and later, the system authentication screen overlays the issuer application UI.

SDK

Android Java

ContactlessTransactionListener paymentCallback = new ContactlessTransactionListener() {
    @Override
    public void onAuthenticationRequired(@NonNull VerificationMethod method) {
        // At this stage, the issuer application calls the D1 SDK
        // authentication API and lets the D1 SDK manage the
        // Android device authentication screen.

        // Create the AuthenticationParameter.
        AuthenticationParameter params = new AuthenticationParameter(
            activity, // The Activity that hosts authentication
            "Custom authentication title",
            "Custom authentication subtitle",
            "Authentication description", // Include the transaction amount
            "Cancel-button-label", // Label for the cancel button
            new DeviceAuthenticationCallback() {
                @Override
                public void onSuccess() {
                    // Authentication succeeds.
                    // The payment flow continues to the next stage: onReadyToTap().
                }

                @Override
                public void onFailed() {
                    // Authentication fails.
                    // The issuer application can ask the end user to retry
                    // by calling startAuthenticate() again.
                }

                @Override
                public void onHelp(int fpCode, @NonNull CharSequence fpDetail) {
                    // For biometric authentication only.
                    // The issuer application can show the fpDetail message.
                }

                @Override
                public void onError(int fpErrorCode) {
                    // For biometric authentication only.

                    // An error occurs during biometric authentication.
                    // For example, the sensor can be locked after multiple failed attempts.
                    // The issuer application should handle the error and guide the end user.
                }
            }
        );

        // Trigger authentication through the D1 SDK.
        startAuthenticate(params);
    }

    // ...
}