> 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-ios/implement-nfc-wallet/make-payments/replenish-payment-keys.md).

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

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

## Prerequisites

### Configure replenishment thresholds (onboarding)

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

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

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

#### Proactive check

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

```swift
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).

{% hint style="info" %}
Trigger replenishment as soon as the SDK indicates it is needed. Avoid terminating the app while replenishment is in progress.
{% endhint %}

### Trigger replenishment

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

{% code expandable="true" %}

```swift
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
        }
    }
}
```

{% endcode %}

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.

{% hint style="info" %}
**TSP-Triggered** When you receive `MG:ReplenishmentNeededNotification`call `ReplenishmentService.replenish(digitalCardID:isForced:)` with `isForced: true`.

See [Process MG notifications (replenishment)](/nfc-wallet-sdk-ios/get-started/configuration/4.-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:

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

The question should be specific, self-contained, and written in natural language.
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.