Check card eligibility

Overview

Card eligibility is the first step in Tokenization. It confirms whether a card can be tokenized in the digital wallet application.

The NFC Wallet SDK checks eligibility with the Token Service Provider (TSP).

If the card is eligible, the SDK returns the terms and conditions (T&C) from the TSP. Show the T&C to the end user and collect acceptance before digitization.

Depending on your program, T&C might not be required.

After eligibility and (when required) T&C acceptance, continue with Digitize a card.

SDK integration

Call MGCardEnrollmentService.checkEligibility() to confirm Tokenization eligibility.

Provide:

• EligibilityData
• One of:

  • InstrumentData
  • pushSessionId

EligibilityData includes:

• language: Preferred language (for example, en).
• inputMethod: How card details were collected (for example, issuer application or manual entry).

InstrumentData can be built from:

• encryptedCardData
• issuerPushReceipt

In the push card enrollment use case, the NFC Wallet backend returns pushSessionId to the issuer backend.

Check eligibility with card credentials

In most cases, check eligibility using card credentials. Provide PAN and expiry date. Optionally provide card security code (CSC).

// Get the handler of the Enrollment Service
MGCardEnrollmentService enrollmentService =
        MobileGatewayManager.INSTANCE.getCardEnrollmentService();

// Build the instrument data from encrypted card data and public key
InstrumentData instrumentData =
        new InstrumentData.EncryptedCardDataBuilder(encryptedCardInfo)
                .publicKeyIdentifier(pubKey)
                .build();

// Build the eligibility data
EligibilityData eligibilityData =
        new EligibilityData.Builder(InputMethod.BANK_APP, "en").build();

// Invoke eligibility with listener CardEligibilityListener
enrollmentService.checkEligibility(eligibilityData, instrumentData, new CardEligibilityListener() {
    @Override
    public void onSuccess(TermsAndConditions termsAndConditions, IssuerData issuerData) {
        // If the card is eligible, get the T&C
        String tncContent = termsAndConditions.getContent();
        ContentType tncContentType = termsAndConditions.getContentType();

        // Persist and display the T&C.
        // Collect acceptance before calling digitizeCard(...).
    }

    @Override
    public void onError(MobileGatewayError error) {
        // Card is not eligible, or the request failed.
        // Check error reason and decide whether to retry or stop the flow.
    }
});

Check eligibility with an issuer push receipt

The issuer can initiate enrollment from the issuer application. In this flow, the issuer application sends an issuer push receipt. The digital wallet application uses it to build InstrumentData.

Enrollment using an issuer push receipt is only supported for Mastercard. NFC Wallet supports the MDES Token Connect specification.

Build InstrumentData using the issuer push receipt. Then call checkEligibility(...) as in the card credentials flow.

final String type = "pushAccountReceipt"; // Constant
final String scheme = "MASTERCARD"; // Only supported by Mastercard / MDES
String payload = "..."; // Payload received from issuer app

// Build the instrument data from issuer push receipt
InstrumentData instrumentData =
        new InstrumentData.IssuerPushReceiptBuilder(scheme, type, payload).build();

Check eligibility with a push card enrollment session ID

To avoid handling encrypted card details in the application, the issuer backend can push card details directly to the NFC Wallet backend. The NFC Wallet backend returns an ephemeral push card enrollment session ID (pushSessionId).

// Get the pushSessionId generated by the NFC Wallet backend
String pushSessionId = "....";

// Get the handler of the Enrollment Service
MGCardEnrollmentService enrollmentService =
        MobileGatewayManager.INSTANCE.getCardEnrollmentService();

// Invoke the card eligibility
enrollmentService.checkEligibility(eligibilityData, pushSessionId, new CardEligibilityListener() {
    @Override
    public void onSuccess(TermsAndConditions termsAndConditions, IssuerData issuerData) {
        // If the card is eligible, get the T&C
        String tncContent = termsAndConditions.getContent();
        ContentType tncContentType = termsAndConditions.getContentType();

        // Persist and display the T&C.
        // Collect acceptance before calling digitizeCard(...).
    }

    @Override
    public void onError(MobileGatewayError error) {
        // Card is not eligible, or the request failed.
    }
});

T&C acceptance

After a successful eligibility check, present the terms and conditions (T&C) to the end user when required.

Then, after the end user accepts, create a TermsAndConditionSession and pass it to digitizeCard(...). See Digitize a card.

// From eligibility: retrieve TermsAndConditions.
// Render termsAndConditions.getContent() based on termsAndConditions.getContentType().
// Then, after end user acceptance:
TermsAndConditionSession tncSession = termsAndConditions.accept();

The digital wallet application is responsible for displaying the T&C and collecting acceptance (when required by your program).

If your program allows implicit acceptance, you can call termsAndConditions.accept() without end user interaction.