> 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/get-started/configuration/4.-push-notifications/handle-push-notifications.md).

# Handle push notifications

NFC Wallet uses push notifications to notify your **digital wallet application**. Notifications are sent by the NFC Wallet backend.

{% hint style="info" %}
Handling NFC Wallet push notifications is required to support **LCM**, transaction notifications, and card enrollment flows where the digital card is activated directly by the issuer.
{% endhint %}

### Route notifications using `sender`

Read `userInfo["sender"]` and route the notification to the right handler:

* `CPS`: digital card operations (**LCM**)
* `TNS`: transaction notifications
* `MG`: payment key replenishment triggered by the **TSP**

```swift
func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable : Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
) {
    let sender = userInfo["sender"] as? String

    Task {
        do {
            switch sender {
            case "CPS":
                // Digital card operations (LCM).
                // Call the SDK notification handler. See `NotificationService` in the API reference.
                break

            case "TNS":
                // Transaction notifications.
                // Refresh transaction history. See `TransactionHistoryService` in the API reference.
                break

            case "MG":
                // Key replenishment triggered by the TSP.
                // Trigger replenishment. See `ReplenishmentService` in the API reference.
                break

            default:
                // Non-SDK notifications.
                break
            }

            completionHandler(.newData)
        } catch {
            completionHandler(.failed)
        }
    }
}
```

### Process CPS notifications (digital card operations)

Forward **CPS** push notifications to the SDK using `NotificationService.processNotification()`.

<pre class="language-swift"><code class="lang-swift">let notification = NotificationService()
<strong>do {
</strong>    try await notification.processNotification(forUserInfo: userInfo)
} catch {
    // display the error
}
</code></pre>

The NFC Wallet SDK processes the push and interacts with the NFC Wallet backend.

The SDK can then emit notification events through `NotificationService.notificationEventStream`. Use these events to track the digital card operation.

Supported events:

* `unsupportedPushContent`: Triggered when the push payload is not supported by the SDK.
* `completed`: Triggered when processing completes successfully (for example, after provisioning a card profile and payment keys).
* `serverMessage`: Triggered when the backend returns an instruction. The SDK provides a `serverMessage` object and a `tokenizedId`.

#### Server message

When you receive `serverMessage`, parse the `serverMessage` object to determine which operation the backend requested.

In particular:

* `requestInstallCard`: Request to install a card.
* `requestResumeCard`: Request to move a card from suspended to active.
* `requestSuspendCard`: Request to move a card from active to suspended.
* `requestDeleteCard`: Request to delete a card.

### Process TNS notifications (transactions)

Transaction notifications provide details about completed payment transactions. Use `TransactionHistoryService` to retrieve transaction records.

Through the push notification, the **digital wallet application** obtains the following information via the notification's `userInfo` parameter:

* `userInfo["sender"]`: `TNS`.
* `userInfo["action"]`: `TNS:PaymentTransactionNotification`.
* `userInfo["digitalCardId"]`: Digital card identifier. Use it with `TransactionHistoryService.records(forDigitalCardID:)`.
* `userInfo["transactionRecordType"]`: Present only for co-badged cards. Pass it to `TransactionHistoryService.records(forDigitalCardID:transactionRecordType:)` to fetch only the relevant records (primary or auxiliary).

<pre class="language-swift"><code class="lang-swift">let action = userInfo["action"] as? String
let cardId = userInfo["digitalCardId"] as? String
let recordType = userInfo["transactionRecordType"] as? String

// Check expected action and card id presence.
guard "TNS:PaymentTransactionNotification" == action, let cardId = cardId else {
    // display the error
}

let historyService = TransactionHistoryService()
do {       
<strong>    let records = try await historyService.records(forDigitalCardID: cardId, transactionRecordType: recodType)
</strong>} catch {
    // display the error
}
</code></pre>

### Process MG notifications (replenishment)

The **TSP** can request payment key replenishment. Use `ReplenishmentService` to replenish keys.

Through the push notification, the **digital wallet application** obtains the following information via the notification's `userInfo` parameter:

* `userInfo["sender"]`: `MG`.
* `userInfo["action"]`: `MG:ReplenishmentNeededNotification`.
* `userInfo["digitalCardId"]`: Digital card identifier. Use it with `ReplenishmentService.replenish(digitalCardID:isForced:)`.

<pre class="language-swift"><code class="lang-swift">let action = userInfo["action"] as? String
let cardId = userInfo["digitalCardId"] as? String

// Check expected action and card id presence.
guard "MG:ReplenishmentNeededNotification" == action, let cardId = cardId else {
    // display the error
}

let replenishmentService = ReplenishmentService()
do {       
<strong>    try await replenishmentService.replenish(digitalCardID: cardId, isForced: true)
</strong>} catch {
    // display the error
}
</code></pre>


---

# 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/get-started/configuration/4.-push-notifications/handle-push-notifications.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.