Create device binding (yellow flow)

Visa Cloud Token Framework (CTF) device binding yellow flow occurs when the issuer requires step-up authentication using an ID&V method.

This flow starts the same way as the Create device binding (green flow), then pauses until the end user completes step-up authentication.

Prerequisites:

• The payment card is already tokenized.
• You have a vProvisionedTokenId.
• The end user can authenticate on the device (PIN, passcode, fingerprint, Face ID, etc.).
• The end user can complete the selected ID&V method (for example, OTP).

Flow

Device binding yellow flow.

Step	Description
1	Start the device binding flow from the merchant application using the Thales SDK.
2	Thales SDK generates a device ID and a CTF key pair, then stores the CTF key pair securely on the device.
3	Thales SDK triggers end user authentication on the device.
4	Thales SDK generates and signs the Visa-defined payload.
5	Thales SDK sends the signed payload and the CTF public key to the Thales backend.
6	Thales backend converts the public key into a certificate using a Visa CA.
7	Thales backend enrolls the device and requests device binding to VTS.
8	VTS checks the issuer decision.
9	Issuer requires step-up authentication and provides supported ID&V methods (for example, OTP or app-to-app).
10	Thales backend is informed about the issuer decision.
11	Thales SDK gets the list of ID&V methods and passes them to the merchant application.
12	The merchant application shows the different options to the end user.

SDK integration

Create a binding

Call createBinding from the Thales SDK.

If the issuer requires step-up authentication, the SDK returns an IDVSession in:

• onIssuerAuthenticationRequired (Android)
• idvSessionHandler (iOS)

Android

public void createBinding(VisaCTFHelper visaCTFHelper, FragmentActivity activity) {

    // 1. Start create binding
    visaCTFHelper.createBinding("vProvisionTokenID", "x-correlationId", new TokenBindingListener() {
        
        @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 onIssuerAuthenticationReady(IDVSession pendingBindingSession, OtpActivationStatus otpActivationStatus) {
            // wait for OTP and enter the OTP
            String otp = "";

            // 4. Submit the OTP
            pendingBindingSession.activateBinding(otp);
        }

        @Override
        public void onIssuerAuthenticationRequired(IDVSession pendingBindingSession) {
            List<IDVMethod> idvMethods = pendingBindingSession.getIdvMethods();
            // Logic to display UI to select idvMethod
            IDVMethod idvMethod = idvMethods.get(0);

            // 3. Submit the selected IDV
            pendingBindingSession.selectIdvMethod(idvMethods.get(0));
        }

        @Override
        public void onIssuerAuthenticationError(@Nullable IDVSession pendingBindingSession, TMGClientException e) {
            // Handle error
        }


        @Override
        public void onSuccess() {
            // 5. Success handling
        }

        @Override
        public void onError(TMGClientException e) {
            // Error Handling
        }
    });
}

iOS

// The singleton class to hold required property for visa flow
class VisaService {
    static var shared = VisaService()
    var idvSession: VisaCTFHelper.IDVSession? = nil
    var completionHandler: ((VisaCTFHelper.IDVSession?, TMGError?) -> Void)? = nil
}

let vProvisionedTokenID: String = ""
let correlationID: String = ""
// 1. Start create binding
visaCTFHelper.createBinding(forVProvisionedTokenID: vProvisionedTokenID,
                            correlationID: correlationID,
    deviceAuthenticationHandler: { auth in
        // 2. Device authentication (for example, Face ID)
        let customMessage = "" // Pass in the custom message. e.g: "Authenticate with Face ID"
        auth.startAuthentication(withMessage: customMessage)
    }, idvSessionHandler: { session in
        // 3. Hold the IDV session locally
        VisaService.shared.idvSession = session
        // Continue with ID&V selection and activation
        
    }, completionHandler: { session, error in
        // 4. Handle completion (success or error)
        VisaService.shared.completionHandler?(session, error)
    })

Get the list of ID&V methods

The list of ID&V methods can be retrieved from the IDVSession object.

Android

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

visaCTFHelper.createBinding(vProvisionTokenId, 
                              correlationId, 
                              new TokenBindingListener() {

          

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

          

      });

iOS

Use the IDVSession object that is returned from the createBinding function to call idvMethods to get the list of supported ID&V methods.

guard let idvSession = VisaService.shared.idvSession else {
    // no idv session
    return
}
// 1. Display list of idv methods
do {
    let idvMethods = try idvSession.idvMethods
} catch let error {
    // 2. handle error
}

Select an ID&V method

Android

visaCTFHelper.createBinding(vProvisionTokenId, 
                            correlationId, 
                            new TokenBindingListener() {

        

        @Override
        public void onIssuerAuthenticationRequired(IDVSession idvSession) { 
            // Submit selected idv method
            IDVMethod selectedIdvMethod;
            idvSession.selectIdvMethod(selectedIdvMethod);
        }

        @Override
        public void onIssuerAuthenticationReady(IDVSession idvSession, 
                                                @Nullable OtpActivationStatus status) { 
            // Check otp activation status
            int maxOtpVerificationAllowed = otpActivationStatus.getMaxOtpVerificationAllowed();
            int maxOtpRequestsAllowed = otpActivationStatus.getMaxOtpRequestsAllowed();
            int otpExpiration = otpActivationStatus.getOtpExpiration();
        }

       

    });

If the selected method is OTP-based, the SDK calls onIssuerAuthenticationReady and provides OtpActivationStatus.

OtpActivationStatus is returned only for OTP_EMAIL, OTP_SMS, and OTP_ONLINE_BANKING.

iOS

guard let idvSession = VisaService.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) { (result) in
        if let otpActivationStatus = result {
            // 3.1. Display page to enter OTP value
        
        } else {
            // 3.2. Handle selected idv which is unrelated to otp, for example, asking for Customer Support

        }
    }
} catch let error {
    // handle error
}

// 4. Failure in step 2, selectIDVMethod, will be handled in completionHandler.
VisaService.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 {
        VisaService.shared.idvSession = session
        // 6. Retry the IDV flow.
    }
}

For OTP-based methods, selectIDVMethod returns OtpActivationStatus. Otherwise it returns nil.

Errors are returned in completionHandler.

OtpActivationStatus is returned only for OTP_EMAIL, OTP_SMS, and OTP_ONLINE_BANKING.

Activate the binding

Activate the binding based on the selected ID&V method:

• APP_TO_APP: see Activate device binding with app-to-app.
• CUSTOMER_SERVICE: see Customer service flow.
• OTP_EMAIL, OTP_SMS, and OTP_ONLINE_BANKING: see OTP flow.

If the flow is interrupted while the binding state is PENDING_ACTIVATION, resume it using resumeBinding.

Resume a pending binding

Use resumeBinding when the binding state is PENDING_ACTIVATION.

Get the IDVSession object

Android

// Get IDVSession object
IDVSession bindingState = visaCTFHelper.resumeBinding(vProvisionedTokenId,
                                                                  new TokenBindingListener() {
              
    ......

    @Override
    public void onError(TMGClientException exception) { 
        // Check error
        int errorCode = exception.getErrorCode();
        int errorMessage = exception.getMessage();
    }
});

In cases where an error occurs, the onError callback will be called, otherwise a IDVSession object will be returned.

iOS

let vProvisionedTokenID: String = ""
// 1. Start resume binding
visaCTFHelper.resumeBinding(forVProvisionedTokenID: vProvisionedTokenID,
                            idvSessionHandler: { session in
        // 2. Hold the IDV session locally
        VisaService.shared.idvSession = session
        // 3. Continue with ID&V selection and activation
        
    }, completionHandler: { session, error in
        // 4. binding successful
        if error == nil {
            
        }
    })

After resumeBinding returns an IDVSession, use it to get the list of ID&V methods, select one and activate the binding as mentioned above.

Optional: resume flow examples (Android/iOS)

List<IDVMethod> idvMethods = idvSession.getIdvMethods();guard let idvSession = VisaService.shared.idvSession else { // no idv session return}// 1. Display list of idv methodsdo { let idvMethods = try idvSession.idvMethods} catch let error { // 2. handle error}

Select an ID&V method

IDVMethod selectedIdvMethod;idvSession.selectIdvMethod(selectedIdvMethod);Once the application submits the selected ID&V method, the onIssuerAuthenticationReady callback will be returned to the application.guard let idvSession = VisaService.shared.idvSession else { // no idv session return}// 1. Display list of idv methodsdo { let idvMethods = try idvSession.idvMethods let selectedIdvMethod = idvMethods[0] // user select 1 of the idvMethods available // 2. submit the idv method idvSession.selectIDVMethod(selectedIdvMethod) { (result) in if let otpActivationStatus = result { // 3.1. display page to enter OTP value } else { // 3.2. handle selected idv which is unrelated to otp, for example, asking for Customer Support } }} catch let error { // handle error}// 4. Failure in step 2, selectIDVMethod, will be handled in completionHandler.VisaService.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 { VisaService.shared.idvSession = session // 6. Retry the IDV flow. }}TMGError illustrated above is not exhaustive. Use the most appropriate error code for your case.

Activate the binding

The binding activation can be done by following the steps for the method selected:

• APP_TO_APP: see Activate binding with app-to-app.
• CUSTOMER_SERVICE: see Customer service flow.
• OTP_EMAIL, OTP_SMS, and OTP_ONLINE_BANKING: see OTP flow.