Create device binding

Mastercard Token Authentication Framework (TAF) starts with device binding.

Prerequisites:

• The card has already completed tokenization. The merchant already has a srcDigitalTokenId from the Thales backend.
• The device supports device authentication, such as fingerprint or Face ID.

Before binding the token to the device, the issuer backend authenticates the end user (ID&V). The issuer backend sends an OTP to the end user. The end user enters the OTP in the merchant application.

The merchant application triggers the create binding flow

Trigger a binding flow.

Step	Description
1-2	The end user (through the merchant application) triggers the ID&V flow by calling the Thales SDK with tokenId and a fresh correlationId (for troubleshooting).
3-7	The Thales SDK calls the Thales backend, which reaches Mastercard to retrieve the available ID&V methods.
8-9	The merchant application displays the available ID&V methods and asks the end user to select one. The options are SMS or email.

You can retrieve the list of ID&V methods from the IDVSession object.

Android

Use the IDVSession object to call getIdvMethods to get the list of supported ID&V methods.

public void createBinding(@NonNull MastercardTAFHelper mastercardTAFHelper, @NonNull String tokenID, @NonNull String correlationID) {

    mastercardTAFHelper.createBinding(tokenID,
            correlationID,
            new TokenBindingListener() {

                @Override
                public void onIssuerAuthenticationReady(@NonNull IDVSession idvSession) {

                }

                @Override
                public void onIssuerAuthenticationRequired(IDVSession idvSession) {
                    // Get list of idv methods
                    List<IDVMethod> idvMethods = idvSession.getIdvMethods();
                }

                @Override
                public void onIssuerAuthenticationError(@NonNull IDVSession pendingBindingSession, TMGClientException tmgClientException) {
                    // Check the error or retry
                }

                @Override
                public void onDeviceAuthentication(DeviceAuthentication deviceAuthentication) {
                    // Perform device authentication using biometric
                }

                @Override
                public void onSuccess() {
                    // Handle UI of create binding success
                }

                @Override
                public void onError(TMGClientException exception) {
                    // Check if there's any error
                }
            });
}

iOS

Use the IDVSession object to call idvMethods to get the list of supported ID&V methods.

// The singleton class to hold required properties for the Mastercard flow
class MastercardService {
    static var shared = MastercardService()
    var idvSession: MastercardTAFHelper.IDVSession? = nil
    var completionHandler: ((MastercardTAFHelper.IDVSession?, TMGError?) -> Void)? = nil
}

let tokenID: String = ""
let correlationID: String = ""
// Start create binding
mastercardTAFHelper.createBinding(forTokenID: tokenID, correlationID: correlationID, 
    idvSessionHandler: { idvSession in
        // hold the idv session locally
        MastercardService.shared.idvSession = idvSession
        // List of idv methods
        let methods = idvSession.idvMethods
        // Display idv methods to the user
    },
    deviceAuthenticationHandler: { auth in
        // faceID
        let customMessage = "" // Pass in the custom message. e.g: "Authenticate with Face ID"
        auth.startAuthentication(withMessage: customMessage)
    }, 
    completionHandler: { session, error in
        // hold the completion handler locally
        MastercardService.shared.completionHandler?(session, error)
        // binding successful
        if error == nil {
            
        }
        // Handle error or retry idv session when there is a failure
    }
)

End user selection and OTP sending

End user selects an ID&V method and receives the OTP.

Step	Description
1-2	The end user selects an ID&V method. The merchant application provides the selection to the Thales SDK.
3-7	The Thales SDK calls the Thales backend, which reaches Mastercard, to generate an OTP. The issuer backend then sends the OTP to the end user through the selected channel.

Android

public void selectIDVMethod(@NonNull MastercardTAFHelper mastercardTAFHelper, @NonNull String tokenID, @NonNull String correlationID, @NonNull FragmentActivity activity) {
    mastercardTAFHelper.createBinding(tokenID,
            correlationID,
            new TokenBindingListener() {

                @Override
                public void onIssuerAuthenticationReady(@NonNull IDVSession idvSession) {
                    // validate OTP
                }

                @Override
                public void onIssuerAuthenticationRequired(IDVSession idvSession) {
                    // Get list of idv methods
                    List<IDVMethod> idvMethods = idvSession.getIdvMethods();

                    // Submit selected idv method
                    IDVMethod selectedIdvMethod = idvMethods.get(0);
                    idvSession.selectIDVMethod(selectedIdvMethod);
                }

                @Override
                public void onIssuerAuthenticationError(@NonNull IDVSession pendingBindingSession, TMGClientException tmgClientException) {
                    // Check the error or retry
                }

                @Override
                public void onDeviceAuthentication(DeviceAuthentication deviceAuthentication) {
                    // Perform device authentication using biometric
                }

                @Override
                public void onSuccess() {
                    // Handle UI of create binding success
                }

                @Override
                public void onError(TMGClientException exception) {
                    // Check if there's any error
                }
            });
}

iOS

guard let idvSession = MastercardService.shared.idvSession else {
    // no idv session
    return
}
// 1. Display list of idv methods
do {
    let idvMethods = try idvSession.idvMethods
    let selectedIdvMethod = idvMethods[0] // user select 1 of the idvMethods available
    
    // 2. submit the idv method
    idvSession.selectIDVMethod(selectedIdvMethod) {
        // 3. display page to enter OTP value
    }
} catch let error {
    // handle error
}
        
// 4. Failure in step 2, selectIDVMethod, will be handled in completionHandler.
MastercardService.shared.completionHandler = { (session, error) in
    // 5. Check if it is a selectIDVMethod error.
    if let session = session,
        let error = error,
        error.description == TMGError.invalidIdvMethod.description {
        MastercardService.shared.idvSession = session
        // 6. Retry the IDV flow.
    }
}

The SDK returns the binding activation result through onSuccess or onIssuerAuthenticationError. If activation fails, keep the IDVSession instance returned in onIssuerAuthenticationError. Use it to retry the ID&V flow.

OTP verification

Step	Description
1-2	The end user enters the OTP in the merchant application, which sends it to the Thales SDK.
3-7	The SDK securely conveys the OTP to Mastercard for verification, then returns the result to the merchant application.

Android

public void validateOTP(@NonNull MastercardTAFHelper mastercardTAFHelper, @NonNull String tokenID, @NonNull String correlationID, @NonNull FragmentActivity activity) {
    mastercardTAFHelper.createBinding(tokenID,
            correlationID,
            new TokenBindingListener() {

                @Override
                public void onIssuerAuthenticationReady(@NonNull IDVSession idvSession) {
                    // Activate binding
                    String otp = "12345";
                    idvSession.validateOTP(otp);

                }

                @Override
                public void onIssuerAuthenticationRequired(IDVSession idvSession) {
                    // Get list of idv methods
                }

                @Override
                public void onIssuerAuthenticationError(@NonNull IDVSession pendingBindingSession, TMGClientException tmgClientException) {
                    // Check the error or retry
                }

                @Override
                public void onDeviceAuthentication(DeviceAuthentication deviceAuthentication) {
                    // Perform device authentication using biometric
                    CharSequence title = "title"; //title to be displayed in Biometric authentication popup.
                    CharSequence subTitle = "subTitle"; //subTitle to be displayed in Biometric authentication popup.
                    CharSequence description = "description"; // description to be displayed in Biometric authentication popup.
                    CharSequence negativeButtonText = "negativeButtonText"; // text of the negative button to be displayed in Biometric authentication popup.
                    deviceAuthentication.startAuthentication(activity,
                            title,
                            subTitle,
                            description,
                            negativeButtonText);
                }

                @Override
                public void onSuccess() {
                    // Handle UI of create binding success
                }

                @Override
                public void onError(TMGClientException exception) {
                    // Check if there's any error
                }
            });
}

iOS

guard let idvSession = MastercardService.shared.idvSession else {
    // no idv session
    return
}
do {
    let otp = "123456" // user entered OTP  value
    // 1. submit otp value
    idvSession.validateOTP(otp)
} catch let error {
    // handle error
}
        
// 2. Failure in step 1, validateOTP, will be handled in completionHandler.
MastercardService.shared.completionHandler = { (session, error) in
    // 3. Check if it is a validateOTP error.
    if let session = session,
        let error = error,
        error.description == TMGError.invalidOTPMessage.description {
        MastercardService.shared.idvSession = session
        // 4. Retry the IDV flow.
    }
}