> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/implement-nfc-wallet/make-payment/replenish-payment-keys.md).

# 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.

{% hint style="info" %}
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.
  {% endhint %}

## Prerequisites

### Configure replenishment thresholds (onboarding)

Configure replenishment thresholds during onboarding with the **Thales delivery team**.

{% hint style="info" %}
When you define thresholds, consider:

* **SUK**: Remaining SUK count that triggers replenishment.
* **LUK**: Remaining transaction count and LUK expiration time.
  {% endhint %}

## 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](/nfc-wallet-sdk-android/get-started/configuration/5.-push-notifications/handle-push-notifications.md).

#### 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](/nfc-wallet-sdk-android/implement-nfc-wallet/manage-digital-cards/display-digital-cards.md).

{% code title="Check whether a digital card needs replenishment" %}

```java
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();
}
```

{% endcode %}

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](/nfc-wallet-sdk-android/implement-nfc-wallet/make-payment/implement-contactless-payments/2.-implement-contactless-payment-callbacks.md).
* When the card is set as default.
* After connectivity returns (offline → online).

{% hint style="warning" %}
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.
{% endhint %}

### Trigger replenishment

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

1. Get the card identifier.

   Use the **tokenized card ID** - see [Display digital card](/nfc-wallet-sdk-android/implement-nfc-wallet/manage-digital-cards/display-digital-cards.md#tokenized-card-id-versus-digital-card-id).
2. Send the replenishment request.

   Call `sendRequestForReplenishment(...)` and implement `PushServiceListener`:

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

   <pre class="language-java" data-title="Send a replenishment request"><code class="lang-java">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.
       }
   }
   </code></pre>
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.

{% hint style="info" %}
Avoid terminating the **digital wallet application** while replenishment is in progress.
{% endhint %}

{% hint style="info" %}
**TSP-triggered replenishment**

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

See [Process MG notifications (replenishment)](/nfc-wallet-sdk-android/get-started/configuration/5.-push-notifications/handle-push-notifications.md#process-mg-notifications-replenishment).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/implement-nfc-wallet/make-payment/replenish-payment-keys.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.