Push Notifications

Introduction

The Push Notifications service manages the push notification device registration of the authenticated customer. A registration links the customer's wallet to a single device, so the Paysafe Wallet platform knows where to deliver notifications and in which language and timezone to render them.

Notifications are delivered through the provider that matches the platform of the device:

• APNS (Apple Push Notification service) for iOS devices.
• FCM (Firebase Cloud Messaging) for Android devices.

The provider is derived from the platform of the SDK, so you never set it yourself. You only supply the push notification token issued to your app by APNS or FCM, together with the optional language and timezone used to render notification templates.

note

The raw push notification token is write-only. Responses never return it - they expose only tokenHash, a SHA-256 hash of the token as a lowercase hexadecimal string.

Key Features:

• Retrieve the push notification registration of the current device.
• Register the current device for push notifications, or replace an existing registration.
• Remove the push notification registration of the current device.

Prerequisites

Before integrating the Push Notifications service, ensure you have:

• A valid Paysafe account with appropriate permissions.
• Set up instructions for Paysafe SDK Android or iOS.
• A push notification token for the current device, obtained from Firebase Cloud Messaging on Android or from APNS on iOS.

To get started, initialize the PushNotificationsService instance in your app as shown below:

Kotlin

import com.paysafe.wallet.android.core.wallet.Wallet

val pushNotificationsService = Wallet.getInstance().getPushNotificationsService()

Swift

import PaysafeWallet

let pushNotificationsService = Wallet.instance.pushNotificationsService

Functionalities

Register a Device

Use the register method to create a registration for the current device, or to replace the existing one - for example after the push notification token has been rotated by the operating system.

Kotlin

Use the registerPushNotificationDevice method by providing a DeviceManagementRegisterRequest object. The result is a DeviceManagementResponse object describing the stored registration.

The deviceTokenType property declares the kind of token you are sending - FCM for a Firebase Cloud Messaging registration token, FID for a Firebase Installation ID, or APNS for an Apple Push Notification service device token.

val request = DeviceManagementRegisterRequest(
    token = fcmToken,
    deviceTokenType = DeviceManagementDeviceTokenType.FCM,
    language = "en",
    timezone = "Europe/Sofia"
)

try {
    val device = pushNotificationsService.registerPushNotificationDevice(request)
    // Display the device registration
} catch (exception: Exception) {
    // Handle exception
}

Swift

Use the registerPushNotificationDevice method by providing a DeviceManagementRegisterRequest object. The result is a DeviceManagementResponse object describing the stored registration.

let request = Wallet.DeviceManagementRegisterRequest(
    token: apnsToken,
    language: "en",
    timezone: "Europe/Sofia"
)

pushNotificationsService.registerPushNotificationDevice(request: request, completion: { result in
  switch result {
  case .success(let device):
    // Display the device registration
  case .failure(let error):
    // Handle error
  }
})

The language and timezone properties are optional:

• language must be a lowercase two-letter ISO 639-1 code, for example en. When omitted, the registered wallet language of the customer is used, falling back to en.
• timezone must be an IANA Time Zone Database identifier, for example Europe/Sofia or UTC. It is used to handle scheduled notifications and sleep hours. When omitted, it defaults to UTC.

Get the Registered Device

Kotlin

Use the getPushNotificationDevice method to retrieve the registration of the current device as a DeviceManagementResponse object.

try {
    val device = pushNotificationsService.getPushNotificationDevice()
    // Display the device registration
} catch (exception: Exception) {
    // Handle exception
}

Swift

Use the getPushNotificationDevice method to retrieve the registration of the current device as a DeviceManagementResponse object.

pushNotificationsService.getPushNotificationDevice(completion: { result in
  switch result {
  case .success(let device):
    // Display the device registration
  case .failure(let error):
    // Handle error
  }
})

The returned registration contains the identifier of the registration (deviceId on Android, deviceID on iOS), the delivery provider, the platform and OS version of the device, the appVersion when available, the language and timezone used for notification templates, the tokenHash, and the creation and last change timestamps.

Deregister a Device

Remove the registration when the customer opts out of push notifications, or before you sign them out of the device.

Kotlin

Use the deregisterPushNotificationDevice method to remove the registration of the current device.

try {
    pushNotificationsService.deregisterPushNotificationDevice()
    // The device no longer receives push notifications
} catch (exception: Exception) {
    // Handle exception
}

Swift

Use the deregisterPushNotificationDevice method to remove the registration of the current device.

pushNotificationsService.deregisterPushNotificationDevice(completion: { result in
  switch result {
  case .success:
    // The device no longer receives push notifications
  case .failure(let error):
    // Handle error
  }
})

Error Handling

All methods throw a WalletException (Android) or WalletError (iOS) when the Paysafe Wallet API returns an error. For the full list of error types and recommended handling patterns, see the Error Handling guide.

The types of notifications the customer agreed to receive are managed separately through the Preferences service.