Digitize a card

Overview

After the card passes eligibility checks, and the end user accepts the terms and conditions (T&C) when required, start digitization.

During the digitization:

• The issuer backend returns the Tokenization decision (green flow, yellow flow, or red flow) to the digital wallet application via NFC Wallet.
• If the issuer backend approves (green flow or yellow flow):

  • The Token Service Provider (TSP) creates the digital card and its assets (profile and payment keys).
  • NFC Wallet securely provisions the digital card profile and payment keys in the digital wallet application.

In the yellow flow, the digital wallet application performs ID&V (step-up authentication) before the card can be provisioned.

In the red flow, digitization is declined and the SDK returns an error callback.

Implement the green flow, the yellow flow, or both, based on your program.

Depending on your program, T&C might not be required. If so, the digital wallet application can accept the T&C without end user interaction.

SDK integration

Start card digitization by calling MGCardEnrollmentService.digitizeCard(...).

You shall first implement MGDigitizationListener to track the digitization progress by handling callbacks according to the enrollment color flow:

• In the Green flow (approved, no step-up) the SDK calls these callbacks:

  • onCPSActivationCodeAcquired
  • onComplete

  For details, see Green flow digitization.
• In the yellow flow (approved with step-up) the SDK also calls:

  • onSelectIDVMethod
  • onActivationRequired

  For details, see Yellow flow digitization.

In case of digization error, NFC Wallet SDK emits the callback:

• onError: Digitization failed. Use error.getCode() to decide whether to retry, ask the end user to take action, or route to support.

MGDigitizationListener implementation example

See code snipet below to implement MGDigitizationListener

// build your Digitization listener
public class MyDigitizationListener implements MGDigitizationListener {

    @Override
    public void onCPSActivationCodeAcquired(String digitalCardId, byte[] activationCode) {
        // Receive activationCode to start provisioning for this digitalCardId.
        // See "Trigger a provisioning session".
    }

    @Override
    public void onSelectIDVMethod(IDVMethodSelector idvMethodSelector) {
        // Yellow flow only - Receive the list of ID&V methods
        // See "Yellow flow digization"
    }

    @Override
    public void onActivationRequired(PendingCardActivation pendingCardActivation) {
        // Yellow flow only - selected ID&V method requiring activation
        // See "Yellow flow digization"
   }

    @Override
    public void onComplete(String digitalCardId) {
        // Digitization completed successfully.
    }

    @Override
    public void onError(String digitalCardId, MobileGatewayError error) {
        // Digitization failed.
        // Parse error.getCode() and apply the right retry / recovery logic.
    }
});

Digitize card example

In the example below you can find the code to start digitization.

• In case of green flow, you have to provide an authentication token.

// reference to your Card Digitization listener
// - to track digitization progress using callback
MyDigitizationListener digitizationListener = new MyDigitizationListener();

// Get the enrollment service.
MGCardEnrollmentService enrollmentService =
        MobileGatewayManager.INSTANCE.getCardEnrollmentService();

// From eligibility: retrieve TermsAndConditions.
// See "Check card eligibility".
TermsAndConditionSession tncSession = termsAndConditions.accept();

// Provide the authentication in case of green flow
byte[] authenticationToken = null;

enrollmentService.digitizeCard(tncSession, authenticationToken, digitizationListener);