Handle push notifications

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

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.

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

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().

let notification = NotificationService()
do {
    try await notification.processNotification(forUserInfo: userInfo)
} catch {
    // display the error
}

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

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 {       
    let records = try await historyService.records(forDigitalCardID: cardId, transactionRecordType: recodType)
} catch {
    // display the error
}

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:).

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 {       
    try await replenishmentService.replenish(digitalCardID: cardId, isForced: true)
} catch {
    // display the error
}