Activate binding with OTP

One-time Password (OTP) is used as the ID&V method to activate a pending device binding.

This page continues the flow after Create device binding (yellow flow).

Prerequisites:

• You already started createBinding or resumeBinding.
• The issuer selected an OTP-based ID&V method (for example, OTP_SMS).
• Your merchant application can collect an OTP from the end user.

Flow

OTP device binding flow.

Step	Description
1	The end user selects an OTP option (SMS, email or online banking).
2	The merchant application forwards the selection to the Thales backend.
3–5	Thales backend requests VTS and the issuer to deliver the OTP over the selected channel.
6	The end user enters the OTP in the merchant application. The merchant application owns the UI.
7–8	Thales backend validates the OTP with VTS and the issuer.
9	Thales SDK receives the result and activates the binding locally.
10	Thales backend notifies the merchant/PSP backend that the binding is active.

SDK integration

1. Select an OTP ID&V method

During createBinding or resumeBinding, select one of the OTP ID&V methods:

• OTP_SMS
• OTP_EMAIL
• OTP_ONLINE_BANKING

Android

Once the application submits the selected ID&V method successfully, the onIssuerAuthenticationReady callback will be returned to the application. Otherwise, an onError callback will be returned.

@Override
public void onIssuerAuthenticationRequired(PendingBindingSession pendingBindingSession) { 
    // Submit OTP_SMS ID&V Method
    for (IDVMethod idvMethod : pendingBindingSession.getIdvMethods()) {
        if (idvMethod.getType().equals(IDVType.OTP_SMS)) {
            pendingBindingSession.submitIdvMethod(idvMethod);
        }
    }
}

@Override
public void onIssuerAuthenticationReady(PendingBindingSession pendingBindingSession, 
                                        @Nullable OtpActivationStatus status) {
    
}

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

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 an OTP idv method (OTP_SMS)
    
    // 2. submit the idv method
    idvSession.selectIDVMethod(selectedIdvMethod) { (result) in
        if let otpActivationStatus = result {
            let maxOtpVerificationAllowed = otpActivationStatus.maxOTPVerificationAllowed
            let maxOtpRequestsAllowed = otpActivationStatus.maxOTPRequestsAllowed
            let otpExpiration = otpActivationStatus.otpExpiration
            
            // 3. Display page to enter OTP
        }
    }
} 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.
    }
}

2. Activate the binding

Collect the OTP in your merchant application, then call activateBinding on the IDVSession.

Android

@Override
public void onIssuerAuthenticationReady(IDVSession idvSession, 
                                        @Nullable OtpActivationStatus status) { 
    // Activate binding
    String otp;
    idvSession.activateBinding(otp);
}

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

The result is returned via onSuccess or onIssuerAuthenticationError.

If activation fails, use the IDVSession returned in onIssuerAuthenticationError to retry.

iOS

// 1. OTP value from user input
let otp = ""

guard let idvSession = VisaService.shared.idvSession else {
    // no idv session
    return
}
// 2. Call activate
idvSession.activateBinding(withValue: otp)

VisaService.shared.completionHandler = { (session, error) in
    // 2. Binding successful
    if error == nil {
        
    } else if let error = error,
                let session = session,
                error.description == TMGError.serverErrorWrongOTP.description {
        VisaService.shared.idvSession = session
        // 3. Retry OTP input and display error message
    }
}

The result is returned in completionHandler.

If activation fails, completionHandler returns an IDVSession and an error for retry.