Yellow flow digitization

Overview

The 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 tokenizes cards for multiple issuers.

In this case, the solution must authenticate using ID&V to complete the tokenization.

User experience

See Yellow flow user experience.

Sequence diagram

Yellow flow: select an ID&V method after digitizationApprovedWithIDV.

Integrate SDK

After you Check card eligibility:

1. Call CardDigitizationService.digitizeCard().

2. If Tokenization is approved with conditions (yellow flow):

   • The NFC Wallet SDK emits digitizationApprovedWithIDV.

3. Get the issuer-supported ID&V methods using IDVMethodSelector.getIDVMethodList().

4. Display the methods and let the end user choose one.

5. Notify the NFC Wallet SDK by calling IDVMethodSelector.select(idvID:).

Supported ID&V methods

The NFC Wallet SDK supports the following ID&V methods:

• otpBySMS: Verify the end user with a one-time password (OTP) sent by SMS.

• otpByEmail: Verify the end user with a one-time password (OTP) sent by email.

• customerService: Verify the end user through issuer customer care.

• webService: Verify the end user on the issuer website.

• appToApp: Verify the end user in the issuer application.

  • with cryptogram: The issuer application generates an issuer cryptogram.

  • without cryptogram: The issuer activates the token using the TSP issuer API.

List and select an ID&V method

Use the following example to list the issuer-supported ID&V methods.

func digitizeCard(_ termsAndConditions: CardDigitizationService.TermsAndConditions) async throws {
    // Step 1: Initialize the card digitization service.
    let cardDigitizationService = CardDigitizationService()
    let fcmToken: String = "FACY6074293608087656831WRF1234" // Example only.

    // Step 2: Start the card digitization process.
    try await cardDigitizationService.digitizeCard(withTNC: termsAndConditions.accept(),
                                                  pushToken: fcmToken,
                                                  language: "en")

    // Step 3: Subscribe to digitization events.
    for await state in await cardDigitizationService.eventStream {
        switch state {
        case let .digitizationApprovedWithIDV(_, idvMethodSelector):
            // Yellow flow: list issuer-supported ID&V methods.
            let verificationMethods = idvMethodSelector.getIDVMethodList()
            for method in verificationMethods {
                if method.type == .otpBySMS || method.type == .otpByEmail {
                    /// OTP method.
                } else if method.type == .webService || method.type == .customerService {
                    /// Method handled directly by the issuer.
                } else if method.type == .appToApp {
                    /// App-to-app method using the issuer application.
                }
            }

        default:
            break
        }
    }
}

Use IDVMethod.id when calling IDVMethodSelector.select(idvID:).

Select an ID&V method

case let .digitizationApprovedWithIDV(digitalCardID, idvMethodSelector):

let verificationMethods = idvMethodSelector.getIDVMethodList()
for method in verificationMethods {
    /// list methods to display
}

// ... code for wallet to capture the selected ID&V method ...

// select the method using the method id
try await idvMethodSelector.select(idvID: selectedMethod.id)

ID&V with OTP

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

The NFC Wallet SDK emits activationRequired with PendingCardActivation.State set to otpNeeded.

After the end user enters the OTP, call PendingCardActivation.activate() with the OTP value.

The NFC Wallet SDK provisions the digital card profile in the background. After provisioning completes, the NFC Wallet SDK emits activatedByIDV.

Implement the OTP entry UI

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

Customer service or web service ID&V

If the digital wallet application selects webService or customerService, the issuer manages ID&V directly. This is done through an issuer web portal or issuer customer care.

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

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 emits activationRequired with PendingCardActivation.State set to appToAppSelected.

Use appToAppSelected.requestPayload, appToAppSelected.scheme, and appToAppSelected.source to redirect the end user to the issuer application.

Redirect to the issuer application

The app-to-app ID&V method is supported for Mastercard and Visa. See the Mastercard or Visa specifications for details.

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

There are two possible methods:

• 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(withTAV:) and provide the issuer cryptogram. The NFC Wallet SDK provisions the digital card profile in the background. After provisioning completes, the NFC Wallet SDK emits activatedByIDV.

For AppToApp without cryptogram, call PendingCardActivation.resumeAppToAppActivation(). Then the NFC Wallet backend sends a CPS push notification to the digital wallet application. Process the push as described in Process CPS notifications.

Resume activation

If the ID&V process is interrupted, resume it using the PendingCardActivationSession API.

This lets the end user reselect an ID&V method: otpBySMS, otpByEmail, customerService, webService, or appToApp with cryptogram.