Replenish payment keys

Overview

Payment keys are required to compute EMV cryptograms for contactless payments.

In a Host Card Emulation (HCE) model, payment keys are temporary. Replenish them before they run out to avoid payment interruptions.

This guide covers when to replenish and how to trigger it.

The NFC Wallet SDK supports various payment key types:

• SUK (Single Use Key): A one-time payment key used for each individual transaction. Applicable for Mastercard and Thales EMV White Label (PURE).
• LUK (Limited Use Key): A payment key that can be used for multiple transactions before it expires. Applicable for Visa.

Prerequisites

Configure replenishment thresholds (onboarding)

Configure replenishment thresholds during onboarding with the Thales delivery team.

When you define the thresholds, consider:

• SUK: the remaining SUK count that should trigger replenishment.
• LUK: the remaining transaction count and the LUK expiration time.

SDK Integration

Detect when replenishment is required

Use one (or both) of these signals:

• Proactive check: read DigitalCard.PaymentKeyInfo.needsReplenishment.
• Reactive push (TSP-triggered): process MG:ReplenishmentNeededNotification push notifications from the TSP.

For push delivery and routing, see Handle push notifications.

Proactive check

Check regularly for each digital card, for example after each payment or at app startup.

func checkReplenishment(digitalCard: DigitalCard) async throws -> Bool {
    return try await digitalCard.paymentKeyInfo.needsReplenishment
}

Perform this proactive check:

• After NFC Wallet SDK initialization.
• After a payment.
• When the card is set as default.
• After connectivity returns (offline → online).

Trigger replenishment as soon as the SDK indicates it is needed. Avoid terminating the app while replenishment is in progress.

Trigger replenishment

Call ReplenishmentService.replenish(digitalCardID:) when you decide to replenish.

func replenishment(digitalCard: DigitalCard) async {
    do {
        if try await digitalCard.paymentKeyInfo.needsReplenishment {
            let replenishmentService = ReplenishmentService()
            try await replenishmentService.replenish(digitalCardID: digitalCard.digitalCardID)
         
            // The NFC Wallet backend sends a push notification to confirm the operation.
            // Your app must process it. See "Handle push notifications".
        }
    } catch let error {
        switch (error as? ReplenishmentService.Error) {
            case .networkError:
                break
            case .missingWalletSecureEnrollment:
                break
            case .deviceEnvironmentUnsafe(let error):
                break
            case .clientError(let message):
                break
            case .serverError(let message):
                break
            case .unknown(let underlying):
                break
            @unknown default:
                break
        }
    }
}

After you submit the replenishment request, the NFC Wallet backend sends a push notification. Your application processes it and the SDK retrieves the new payment keys.

TSP-Triggered When you receive MG:ReplenishmentNeededNotificationcall ReplenishmentService.replenish(digitalCardID:isForced:) with isForced: true.

See Process MG notifications (replenishment).