Replenish payment keys

Overview

Payment keys (SUK or LUK) 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. This prevents payment interruptions.

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

The NFC Wallet SDK supports these payment key types:

• SUK (Single Use Key): Use one key per transaction. Used for Mastercard and PURE (white label EMV).
• LUK (Limited Use Key): Use one key for multiple transactions. Used for Visa.

Prerequisites

Configure replenishment thresholds (onboarding)

Configure replenishment thresholds during onboarding with the Thales delivery team.

When you define thresholds, consider:

• SUK: Remaining SUK count that triggers replenishment.
• LUK: Remaining transaction count and LUK expiration time.

SDK integration

Detect when replenishment is required

Use one (or both) of these signals:

• Proactive check: Read the digital card status.
• Reactive push (TSP-triggered): Process MG:ReplenishmentNeededNotification from the TSP.

For push delivery and routing, see Handle push notifications.

Proactive check

Run this check for each digital card. Run it at app startup or after a payment.

1. Get DigitalizedCardStatus from DigitalizedCard.
2. Call DigitalizedCardStatus.needsReplenishment().

See Display digital cards.

Check whether a digital card needs replenishment

public static boolean needsReplenishment(final DigitalizedCard card) {
    AsyncResult<DigitalizedCardStatus> result =
            card.getCardState(null).waitToComplete();

    if (!result.isSuccessful()) {
        // TODO: handle error
        return false;
    }

    DigitalizedCardStatus status = result.getResult();
    return status != null && status.needsReplenishment();
}

Perform this proactive check:

• At regular application startup

  • Do not perform the check if application is stated for a payment - see warning below
• After a payment

  • On event onNextTransactionReady - see implement contactless payment callbacks.
• When the card is set as default.
• After connectivity returns (offline → online).

Run this check at application startup, after NFC Wallet SDK initialization.

Do not run this check when the end user launches the application to make a contactless payment. It can delay payment execution.

Trigger replenishment

Call ProvisioningBusinessService.sendRequestForReplenishment(...) to request new payment keys.

1. Get the card identifier.

   Use the tokenized card ID - see Display digital card.
2. Send the replenishment request.

   Call sendRequestForReplenishment(...) and implement PushServiceListener:

   • onComplete: The request is accepted.
   • onError: The SDK cannot send the request. Inspect ProvisioningServiceError.

   Send a replenishment request

   public void replenish(final String tokenizedCardId, final boolean forced) {
       ProvisioningBusinessService service =
               ProvisioningServiceManager.getProvisioningBusinessService();
   
       service.sendRequestForReplenishment(
               tokenizedCardId,
               new ReplenishmentListener(),
               forced
       );
   }
   
   private static class ReplenishmentListener implements PushServiceListener {
       @Override
       public void onComplete() {
           // TODO: log success
       }
   
       @Override
       public void onError(final ProvisioningServiceError error) {
           // TODO: log error
       }
   
       @Override
       public void onUnsupportedPushContent(final Bundle bundle) {
           // Not used for this call.
       }
   
       @Override
       public void onServerMessage(final String tokenizedCardId,
                                   final ProvisioningServiceMessage message) {
           // Not used for this call.
       }
   }

3. Process the replenishment push.

   After you submit the request, the NFC Wallet backend sends a push notification. Your digital wallet application must process it. The SDK then retrieves the new payment keys.

Avoid terminating the digital wallet application while replenishment is in progress.

TSP-triggered replenishment

When you receive MG:ReplenishmentNeededNotification, trigger replenishment with forced = true.

See Process MG notifications (replenishment).