Communication Preferences

Introduction

The Communication Preferences service enables customers to manage their communication preferences across different categories and channels. These preferences control how customers receive communications from Paysafe, organized into distinct categories with support for hierarchical relationships between parent and child categories.

Key Features

• Get all communication preferences or filter by specific categories.
• Update communication preferences for specific categories and channels.
• Support for hierarchical category relationships (parent/child).
• Channel-specific settings with editable and effective state tracking.
• Support for email, SMS, and push notification channels.

Prerequisites

Before integrating the Communication Preferences service, ensure you have:

• A valid Paysafe account with appropriate permissions.
• Set up instructions for Paysafe SDK Android or iOS.

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

Kotlin

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

val communicationPreferencesService = Wallet.getInstance().getCommunicationPreferencesService()

Swift

import PaysafeWallet

let communicationPreferencesService = Wallet.instance.communicationPreferencesService

Get Communication Preferences

Retrieve the customer's communication preferences, grouped by category and channel. Categories are returned sorted for display, with parent categories always appearing before their children.

Kotlin

Use the get method to retrieve all CommunicationPreferences or filter by specific categories.

try {
    // Get all communication preferences
    val preferences = communicationPreferencesService.get()
    // Handle preferences
} catch (exception: Exception) {
    // Handle error
}

To filter by specific categories:

try {
    val categories = listOf("PAYMENTS", "DEPOSIT")
    val preferences = communicationPreferencesService.get(categories)
    // Handle filtered preferences
} catch (exception: Exception) {
    // Handle error
}

Swift

Use the get method to retrieve all CommunicationPreferences or filter by specific categories.

communicationPreferencesService.get(completion: { result in
  switch result {
  case .success(let preferences):
    // Handle preferences
  case .failure(let error):
    // Handle error
  }
})

To filter by specific categories:

let categories = ["PAYMENTS", "DEPOSIT"]
communicationPreferencesService.get(categories: categories, completion: { result in
  switch result {
  case .success(let preferences):
    // Handle filtered preferences
  case .failure(let error):
    // Handle error
  }
})

note

When filtering by categories, a matched child category may be returned without its parent. If no categories match the filter, an empty list is returned.

Update Communication Preferences

Update the customer's communication preferences for specific categories and channels. Only the supplied categories and channels are modified; omitted ones remain unchanged. Only channels marked as editable can be updated.

Kotlin

Use the update method with a CommunicationPreferencesUpdate object to modify preferences.

val preferencesUpdate = CommunicationPreferencesUpdate(
    categories = listOf(
        CommunicationPreferenceCategoryUpdate(
            code = "PAYMENTS",
            channels = listOf(
                CommunicationPreferenceChannelUpdate(
                    channel = CommunicationChannel.EMAIL,
                    enabled = true
                ),
                CommunicationPreferenceChannelUpdate(
                    channel = CommunicationChannel.SMS,
                    enabled = false
                )
            )
        )
    )
)

try {
    val updatedPreferences = communicationPreferencesService.update(preferencesUpdate)
    // Handle updated preferences
} catch (exception: Exception) {
    // Handle error
}

Swift

Use the update method with a CommunicationPreferencesUpdate object to modify preferences.

let preferencesUpdate = Wallet.CommunicationPreferencesUpdate(
    categories: [
        Wallet.CommunicationPreferenceCategoryUpdate(
            code: "PAYMENTS",
            channels: [
                Wallet.CommunicationPreferenceChannelUpdate(
                    channel: .email,
                    enabled: true
                ),
                Wallet.CommunicationPreferenceChannelUpdate(
                    channel: .sms,
                    enabled: false
                )
            ]
        )
    ]
)

communicationPreferencesService.update(preferences: preferencesUpdate, completion: { result in
  switch result {
  case .success(let updatedPreferences):
    // Handle updated preferences
  case .failure(let error):
    // Handle error
  }
})

warning

Only channels marked as editable can be updated. Attempting to update non-editable channels may result in an error or the changes being ignored.

info

The returned preferences may include values that were not explicitly sent in the update. For example, disabling a parent category changes the effective value of every child category.

Communication Channels

The service supports the following communication channels:

Channel	Description
EMAIL	Delivered to the customer's registered email address
SMS	Delivered as a text message to the customer's registered mobile number
PUSH_NOTIFICATION	Delivered as a push notification to the customer's registered devices
UNKNOWN	Returned when no valid channel value was found

Understanding Channel States

Each communication preference channel has multiple state properties:

• enabled: Whether the customer has enabled this channel for the category, after applying configured, customer chosen, and default settings.
• effective: The state that applies after inherited (parent) settings and system constraints. May differ from enabled.
• editable: Whether the customer is allowed to change the enabled setting.

Category Hierarchy

Communication preferences support a hierarchical structure with parent and child categories:

• Parent categories always appear before their children in the response.
• The hierarchy is limited to one level of nesting.
• When filtering by categories, a referenced parent may be absent from the response.
• Disabling a parent category affects the effective state of all child categories.