Enroll the authenticator

Overview

Before completing a 3DS challenge during an e‑commerce transaction, the end user must enroll a device authenticator in the issuer application.

The D1 SDK provides a FIDO‑based authenticator for EMV 3‑D Secure (3DS). Enrollment registers the end user’s authenticator on the device for 3DS.

Enrollment flow

High‑level authenticator enrollment flow.

Sequence diagram

The diagram below shows the end‑to‑end message sequence for authenticator enrollment.

Prerequisites

• The issuer application integrates the D1 SDK and the SDK is initialized.
• The issuer application is logged in to the D1 SDK.
• The end user is registered in the D1 Platform.
• Push notifications are configured in the issuer application.

Sequence diagram for authenticator enrollment.

• Each device supports a maximum of one enrolled end user.
• A single end user may be enrolled on multiple devices.
• Certain Android devices may generate an incorrect attestation payload, which can result in enrollment failure. To mitigate this risk, it is strongly recommended to enroll using a BIOMETRIC authenticator rather than a PLATFORM authenticator.

D1 SDK integration

Enroll the authenticator

Android Java

// Provide an AuthnCallback
D1Authn d1Authn = d1Task.getD1Authn(activity, authnCallback);

// Select the authenticator type
AuthnType preferredAuthnType = AuthnType.BIOMETRIC;

d1Authn.enrollAuthnCredentials(preferredAuthnType, new D1Task.Callback<Void>() {
    @Override
    public void onSuccess(Void unused) {
        // The device is enrolled for 3DS. Continue with the OOB challenge.
    }

    @Override
    public void onError(@NonNull D1Exception e) {
        // Handle the error in your app.
    }
});

Android Kotlin

fun enrollAuthnCredentials(d1Task: D1Task, activity: FragmentActivity, authnCallback: AuthnCallback) {
    // Implement the interface conforming to the AuthnCallback
    val d1Authn: D1Authn = d1Task.getD1Authn(activity, authnCallback)

    // Select your preferred authenticator type
    val preferredAuthnType: AuthnType = AuthnType.BIOMETRIC

    d1Authn.enrollAuthnCredentials(preferredAuthnType, object : D1Task.Callback<Void?> {
        override fun onSuccess(unused: Void?) {
            // Proceed with subsequent flows, the device is now enrolled for 3D Secure service.
        }

        override fun onError(e: D1Exception) {
            // Refer to D1 SDK Integration – Error Management section.
        }
    })
}

iOS

// Conform to AuthnDelegate
let d1Authn = d1Task.d1Authn(self)

// Select the authenticator type
let preferredAuthnType = AuthnType.biometric

d1Authn.enrollAuthnCredentials(preferredAuthnType, completion: { error in
    if let error = error {
        // Handle the error in your app.
    } else {
        // The device is enrolled for 3DS. Continue with the OOB challenge.
    }
})

Next, proceed to Handle the OOB challenge.

Unenroll the authenticator

Call unenrollAuthnCredentials to remove enrollment on this device. The D1 backend and local device storage delete associated enrollment data. Other devices remain enrolled. If the device is already unenrolled, the call succeeds (idempotent).

Android Java

// Provide an AuthnCallback
D1Authn d1Authn = d1Task.getD1Authn(activity, authnCallback);

d1Authn.unenrollAuthnCredentials(new D1Task.Callback<Void>() {
    @Override
    public void onSuccess(Void unused) {
        // The device is unenrolled for 3DS.
    }

    @Override
    public void onError(@NonNull D1Exception e) {
        // Handle the error in your app.
    }
});

Android Kotlin

fun unenrollAuthnCredentials(d1Task: D1Task, activity: FragmentActivity, authnCallback: AuthnCallback) {
    // Implement the interface conforming to the AuthnCallback
    val d1Authn: D1Authn = d1Task.getD1Authn(activity, authnCallback)

    d1Authn.unenrollAuthnCredentials(object : D1Task.Callback<Void?> {
        override fun onSuccess(unused: Void?) {
            // the device is now unenrolled for 3D Secure service.
        }

        override fun onError(@NonNull e: D1Exception) {
            // Refer to D1 SDK Integration – Error Management section. It may fail due to network connection.
        }
    })
}

iOS

// Conform to AuthnDelegate
let d1Authn = d1Task.d1Authn(self)

d1Authn.unenrollAuthnCredentials({ error in
    if let error = error {
        // Handle the error in your app.
    } else {
        // The device is unenrolled for 3DS.
    }
})

Customize the prompt message

Android For BIOMETRIC, you can customize the message shown in the biometric prompt dialog. For PLATFORM, customizing the prompt message is not supported.

iOS Customizing the authentication prompt message is not supported.

Android Java

public void customizingBiometricPromptMessage(@NonNull D1Task d1Task, @NonNull FragmentActivity activity) throws D1Exception {
    // Select your preferred authenticator type as AuthnType.BIOMETRIC
    AuthnType preferredAuthnType = AuthnType.BIOMETRIC;

    String customMessage = "Please authenticate with biometrics";

    d1Task.getD1Authn(activity, new AuthnCallback() {
        @Override
        public void onTransactionDataConfirmation(@NonNull Map<String, String> map, @NonNull AuthnUserConfirmationCallback authnUserConfirmationCallback) {
            // The 'map' contains the transaction data that is to be authenticated.
            // Application to display the content, prompt end uer either to 'proceed' or to 'deny' the authentication request.
        }

        @NonNull
        @Override
        public String onBiometricPromptMessage() {
            return customMessage;
        }
    });
}

Android Kotlin

@Throws(D1Exception::class)
fun customizingBiometricPromptMessage(d1Task: D1Task, activity: FragmentActivity) {
    // Select your preferred authenticator type as AuthnType.BIOMETRIC
    val preferredAuthnType = AuthnType.BIOMETRIC

    val customMessage = "Please authenticate with biometrics"

    d1Task.getD1Authn(activity, object : AuthnCallback {
        override fun onTransactionDataConfirmation(map: Map<String, String>, authnUserConfirmationCallback: AuthnUserConfirmationCallback) {
            // The ‘map’ contains the transaction data that is to be authenticated.
            // Application to display the content, prompt end user either to ‘proceed’ or to ‘deny’ the authentication request.
        }

        override fun onBiometricPromptMessage(): String {
            return customMessage
        }
    })
}