Yellow flow digitization

Overview

Yellow flow is a Tokenization flow where the issuer backend approves Tokenization with step-up authentication (ID&V).

This flow is common when the NFC Wallet SDK is integrated into a digital wallet application that supports cards from multiple issuers.

In this flow, the end user completes ID&V before Tokenization can complete.

User experience

See Yellow flow user experience.

Sequence diagram

Yellow flow digitization sequence.

Integrate SDK

After you Check card eligibility, implement MGDigitizationListener to track digitization progress. Then:

1. Call MGCardEnrollmentService.digitizeCard(...).

   Provide a reference to your MGDigitizationListener.
2. If the issuer backend approves Tokenization with step-up authentication (yellow flow), the SDK triggers these callbacks:

   1. onCPSActivationCodeAcquired

      You receive the activationCode to start the secure provisioning.

      See Trigger provisioning.
   2. onSelectIDVMethod: Receive the ID&V methods to display to the end user. See List and select an ID&V method.
   3. onActivationRequired: Triggered only if the selected ID&V method requires activation (for example, OTP).
   4. onComplete: Digitization steps is completed successfully.

      if ID&V methods are:

      1. cell_phone, email or app_to_app with cryptogram: Tokenization is completed
      2. website, customer_service, or app_to_app without cryptogram: Tokenization is completed after your process CPS notifications.

For the website, customer_service, or app_to_app without cryptogram ID&V methods, the issuer activates the token using the TSP issuer API.

In this case, provisioning completes only after you process CPS notifications.

List and select an ID&V method

In MGDigitizationListener.onSelectIDVMethod, use IDVMethodSelector to list the available ID&V methods.

IDVMethodSelector.getIdvMethodList() returns an array of IDVMethod with these fields:

• id: Use this value when selecting the method.
• type: The ID&V type (for example, OTP by SMS, OTP by email, or verification by issuer application).
• value: The display value. The content depends on type.
• isOTPRequired: Indicates whether the SDK will trigger onActivationRequired.

NFC Wallet supports these ID&V type values:

• cell_phone

  ID&V using an OTP sent by SMS.

  Use value to display the masked phone number where the OTP will be sent.
• email

  ID&V using an OTP sent by email.

  Use value to display the masked email address where the OTP will be sent.
• customer_service

  ID&V using a call to issuer customer care.

  Use value to display the phone number the end user must call.
• website

  The end user completes ID&V on the issuer website.

  Use value to get the website URL.
• app_to_app

  The digital wallet application redirects the end user to the issuer application.

  Use value to display the issuer application name.

When the end user selects a method, capture its id and call IDVMethodSelector.select(...) to notify the NFC Wallet backend.

// Reference of the idvMethodSelector
IDVMethodSelector idvMethodSelector = null;

// Methods from interface MGDigitizationListener 
@Override
public void onSelectIDVMethod(final IDVMethodSelector idvMethodSelector) {
    if (idvMethodSelector.getIdvMethodList().length == 0) {
        // Log error
    }
    
    this.idvMethodSelector = idvMethodSelector;
    
    displayIdvMethods();
}

// Method to build Dialog UI to display possible ID&V...
public void displayIdvMethods() {
    // ... so list of possible ID&V using idvMethodSelector
    for (int i = 0; i < idvMethodSelector.getIdvMethodList().length; i++) {
        IDVMethod idvMethod = idvMethodSelector.getIdvMethodList()[i];
        String id = idvMethod.getId();
        String type = idvMethod.getType();
        String value = idvMethod.getValue();
        boolean isOtpRequired = idvMethod.isOtpRequired();
        ...
    }
    ...
}

// Method to be called from UI, when the ID&V method is selected by end user
// Provide the id of the selected idvMethod
public void selectIdvMethod( int idvSelectedMethodId) {
    idvMethodSelector.select( idvSelectedMethodId );
}

ID&V with OTP

If the end user selects cell_phone or email, the TSP generates an OTP. Then the TSP requests the issuer to send the OTP by SMS or email.

The NFC Wallet SDK triggers MGDigitizationListener.onActivationRequired with PendingCardActivation.getState() set to OTP_NEEDED.

Your digital wallet application must display an OTP entry UI.

After the end user enters the OTP, call PendingCardActivation.activate(...) and provide the OTP.

If the OTP is valid, the SDK triggers MGDigitizationListener.onComplete callback.

Implement the OTP entry UI

The NFC Wallet SDK does not provide an OTP entry UI. Implement and customize the UI in your digital wallet application.

// reference to your Card Digitization listener
MyDigitizationListener digitizationListener = new MyDigitizationListener();

// Reference of the pending card activation
PendingCardActivation pendingCardActivation = null;

// Methods from interface MGDigitizationListener 
@Override
public void onActivationRequired (PendingCardActivation pendingCardActivation) {
    this.pendingCardActivation = pendingCardActivation;
    
    PendingCardActivation activationState = pendingCardActivation.getState();
    switch( activationState ) {
        case OTP_NEEDED:
            // display a UI to enter an OTP
            ...
    }
    ...
}

// Method to be called from UI, when the OTP has been provided by end user
public void idvActivationWithOtp( String otp) {
    pendingCardActivation.activate( otp.getBytes(), digitizationListener );
}

Customer service or web service ID&V

If the end user selects customer_service or website, the issuer manages ID&V directly (for example, via an issuer web portal or issuer customer care).

Use value to get the web portal URL or the issuer customer care phone number.

After the issuer successfully authenticates the end user, the issuer activates the token using the TSP issuer API.

Then the NFC Wallet backend sends a CPS push notification to the digital wallet application.

Process the push as described in Process CPS notifications.

App-to-app ID&V

In this ID&V method, the digital wallet application redirects the end user to the issuer application.

The NFC Wallet SDK triggers MGDigitizationListener.onActivationRequired with PendingCardActivation.getState() set to APP2APP_NEEDED.

Use PendingCardActivation.getAppToAppData() to retrieve an AppToAppData object.

Use AppToAppData.getPayLoad(), AppToAppData.getScheme(), and AppToAppData.getSource() to redirect the end user to the issuer application.

MGCardEnrollmentService enrollmentService = MobileGatewayManager.INSTANCE.getCardEnrollmentService();
PendingCardActivation pendingCardActivation = enrollmentService.getPendingCardActivation(digitalCardId);
PendingCardActivationState state = pendingCardActivation.getState();
if (PendingCardActivationState.APP2APP_NEEDED == state) {
  AppToAppData appToAppData = pendingCardActivation.getAppToAppData();
  if(appToAppData != null) {
    String scheme = appToAppData.getScheme();
    String source = appToAppData.getSource();
    String payload = appToAppData.getPayload();
  // use source to get packageId and intent action to launch issuer application
  }
}

After the issuer application completes authentication, it redirects the end user back to the digital wallet application.

There are two variants:

• AppToApp with cryptogram: The issuer application generates an issuer cryptogram.
• AppToApp without cryptogram: The issuer activates the token using the TSP issuer API.

For AppToApp with cryptogram,

• call PendingCardActivation.resumeAppToAppActivation(...) and provide the issuer cryptogram.
• If the cryptogram is valid,

  • The NFC Wallet SDK provisions the digital card profile in the background.
  • and the SDK triggers MGDigitizationListener.onComplete callback.

For AppToApp without cryptogram,

• call PendingCardActivation.resumeAppToAppActivation().
• Process the push as described in Process CPS notifications.