Create device binding (green flow)

Use the Visa Cloud Token Framework (CTF) device binding green flow when the issuer approves device binding without step-up authentication.

In Production, device binding often requires step-up authentication. That path is the yellow flow.

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

Flow

Device binding green 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 store the CTF key pair securely on the device.
3	Thales SDK triggers the 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 request device binding to VTS.
8	VTS checks the issuer decision.
9	Issuer approves the device binding without step-up authentication.
10	VTS forwards the result to the Thales backend.
11	Thales SDK is informed and binds the token identifier locally to the device.
12	Thales backend notifies the merchant/PSP backend with the binding details.

SDK integration

Create a binding

Android

String vProvisionedTokenId;
String correlationId;

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

        ......
        
        @Override
        public void onDeviceAuthentication(DeviceAuthentication deviceAuthentication) {
            // Do user authentication
         }

        @Override
        public void onSuccess() { }

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

iOS

let vProvisionedTokenID: String = ""
let correlationID: String = ""
// 1. Start create binding
visaCTFHelper.createBinding(forVProvisionedTokenID: vProvisionedTokenID,
                            correlationID: correlationID,
    deviceAuthenticationHandler: { auth in
        // 2. faceID
        let customMessage = "" // Pass in the custom message. e.g: "Authenticate with Face ID"
        auth.startAuthentication(withMessage: customMessage)
    }, idvSessionHandler: { session in
        // Start idv session (only applicable for yellow flow)
        
    }, completionHandler: { session, error in
        // 3. binding successful
        if error == nil {
            
        }
        // Handle error or retry idv session when there is a failure (not applicable for green flow)
    })

createBinding is asynchronous. It is recommended to call runOnUiThread(Runnable) on the function callback in cases where the application has to update any UI.

Authenticate the end user

Creating a device binding requires end user presence. Implement the deviceAuhenticationHandler callback from createBinding.

Use this callback to present any custom UI (for example, Face ID permission prompts). Start authentication by calling startAuthentication. You can also pass a custom message to display during authentication.

Android

@Override
public void onDeviceAuthentication(DeviceAuthentication deviceAuthentication) {
    FragmentActivity fragmentActivity;
    CharSequence title;
    CharSequence subTitle;
    CharSequence description;
    CharSequence negativeButtonText;

    // Start user authentication
    deviceAuthentication.startAuthentication(fragmentActivity, 
                                             title, 
                                             subTitle, 
                                             description, 
                                             negativeButtonText);
}

iOS

let deviceAuhenticationHandler: ((DeviceAuthentication) -> Void) = {(auth) in
    // Start user authentication
    let customMessage = "" // Pass in the custom message. e.g: "Authenticate with Face ID"
    auth.startAuthentication(withMessage: customMessage)
}

Handle results

Results are returned via the onSuccess or onError callback.

On error, log and inspect the exception error code and message.

Android

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

iOS

let vProvisionedTokenID: String = ""
let correlationID: String = ""
// 1. Start create binding
visaCTFHelper.createBinding(forVProvisionedTokenID: vProvisionedTokenID,
                            correlationID: correlationID,
    deviceAuthenticationHandler: { auth in
        // 2. cancel device authentication
        auth.cancel()
    }, idvSessionHandler: { session in
        // Start idv session (only applicable for yellow flow)
        
    }, completionHandler: { session, error in
        if error == nil {
            
        }
        // 3. Handle the cancel error
    })