Check card eligibility

Overview

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

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

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

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

SDK integration

Use CardDigitizationService.checkEligibility to confirm Tokenization eligibility. If eligible, the NFC Wallet backend returns the applicable Terms & Conditions (T&C).

To perform the eligibility check, provide EligibilityData and either InstrumentData or pushSessionID.

EligibilityData includes:

• language: The preferred language for the operation (for example, en).

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

Then provide either:

• InstrumentData: Built from either encryptedCardData or an issuerPushReceipt. Treat card data as sensitive and always send it encrypted.

• pushSessionID: A unique identifier generated by the NFC Wallet backend. The issuer backend receives it during push card enrollment.

Check eligibility with card credentials

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

Send the card credentials in encrypted form.

In the standard flow, the issuer backend supplies card credentials. The digital wallet application uses them for eligibility checks.

The following code snippet shows how to check eligibility using encryptedCardData:

func triggerCheckEligibility(_ pubKey: String, _ encryptedData: Data) async throws {
    do {
        let encryptedDataComponent = CardDigitizationService.InstrumentDataComponents(encryptedCardData: encryptedData, publicKeyIdentifier: pubKey)
        let instrumentData = encryptedDataComponent.instrumentData()
        // Builds the eligible data
        let eligibilityDataBuilder = CardDigitizationService.EligibilityDataComponents(inputMethod: .bankApp, language: "en")
        let eligibilityData = eligibilityDataBuilder.eligibilityData()
        let cardDigitizationService = CardDigitizationService()
        let acceptanceData = try await cardDigitizationService.checkEligibility(eligibilityData, instrumentData: instrumentData)
        let tnc = acceptanceData.termsAndConditions
        // Stores the T&C, notifies UI and wait for response.
    } catch let error as CardDigitizationService.Error {
        // Handles the error.
    }
}

Check eligibility with an issuer push receipt

The issuer can initiate card 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.

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

The following code snippet shows how to build InstrumentData using an issuer push receipt. Then call checkEligibility the same way as when using card credentials.

func triggerCheckEligibility(_ payload: String, _ scheme: DigitalCard.Scheme) async throws {
    do {
        let pushReceiptDataComponent = CardDigitizationService.InstrumentDataComponents(scheme: scheme, payload: payload)
        let instrumentData = pushReceiptDataComponent.instrumentData()
        // Builds the eligible data.
        let eligibilityDataBuilder = CardDigitizationService.EligibilityDataComponents(inputMethod: .bankApp, language: "en")
        let eligibilityData = eligibilityDataBuilder.eligibilityData()
        let cardDigitizationService = CardDigitizationService()
        let acceptanceData = try await cardDigitizationService.checkEligibility(eligibilityData, instrumentData: instrumentData)
        let tnc = acceptanceData.termsAndConditions
        // Stores the T&C and notifies UI, and wait for response.
    } catch let error as CardDigitizationService.Error {
        // Handles the error.
    }
}

Check eligibility with a push card enrollment session ID

To avoid sharing encrypted card details in the application, the digital wallet backend can push card details directly to the NFC Wallet backend. The NFC Wallet backend returns an ephemeral push card enrollment session ID (pushSessionID).

The following code snippet shows how to continue card enrollment by checking eligibility using the push card enrollment session ID.

func triggerCheckEligibility(_ pushSessionID: String) async throws {
    do {
        // Builds eligibility data.
        let eligibilityDataBuilder = CardDigitizationService.EligibilityDataComponents(inputMethod: .onFile, language: "en")
        let eligibilityData = eligibilityDataBuilder.eligibilityData()
        let cardDigitizationService = CardDigitizationService()
        let acceptanceData = try await cardDigitizationService.checkEligibility(eligibilityData, pushSessionID: pushSessionID)
        let tnc = acceptanceData.termsAndConditions
        // Stores the T&C, notifies UI and wait for response.
    } catch let error as CardDigitizationService.Error {
        // Handles the error.
    }
}