Wearables SDK

Version 2.1.7

Table of Contents

1. Wearables SDK overview

   1.1. What is Wearables SDK?

   1.2. Versioning and backward compatibility

   1.3. Prerequisites

2. Technical overview

   2.1. Basic information

   2.2. Basic configuration

   2.3. Wearables SDK Setup

   2.4. Integration tips

   2.5. Error handling

3. Processes

   3.1 Establishing connection

   3.2 Synchronization

   3.3 Adding token

4. Wearables Service

   4.1. startConnectionService

   4.2. stopConnectionService

   4.3. isConnectionServiceRunning

   4.4. establishScopedConnection

   4.5. getAvailableWearables

   4.6. syncStatus

   4.7. registerConnectionCallback

   4.8. unregisterConnectionCallback

   4.9. registerReportingCallback

   4.10. unregisterReportingCallback

   4.11. unpairConnectedDevice

   4.12. isAppInstalledOnWearable

5. Token Service

   5.1. getWearablesIdsPairedWithToken

   5.2. isWearablePairedWithToken

   5.3. removeToken

   5.4. removeAllTokens

   5.5. addToken

   5.6. addTokenCredentials

   5.7. handleTokenStatusChange

   5.8. handleReplenishSuccess

6. Development Service

   6.1 dumpLogs

7. Interfaces requiring implementation

   7.1 ReportingCallback

   7.1.1 onNewReport

   7.1.2 Report categories

   7.2 ConnectionCallback

   7.2.1 onConnectionMonitorRegistered

   7.2.2 onConnected

   7.2.3 onDisconnected

   7.2.4 onAppNotInstalled

   7.3 TokenizationDataProvider

   7.3.1 createSecureSession

   7.3.2 getEncryptedToken

   7.3.3 getEncryptedTokenTransactionCredentials

   7.3.4 updateTokenCredentials

   7.3.5 getTokenizedPaymentInstruments

   7.3.6 triggerCredentialsReplenish

   7.3.7 deleteTokenizedPaymentInstrument

   7.3.8 pairDevice

   7.3.9 isDevicePaired

   7.4 ConsentProvider

   7.4.1 canPerformSync

   7.4.2 canAutomaticallyStartConnectionService

   7.5 TokenCallback

   7.5.1 onCredentialsAdded

8. Document changelog

   8.1. Version 1.1.3

   8.2. Version 1.1.4

   8.3. Version 1.1.5

   8.4. Version 1.1.6

   8.5. Version 1.1.7

   8.6. Version 1.1.8

   8.7. Version 1.1.9

   8.8. Version 2.0.0

   8.9. Version 2.0.1

   8.10. Version 2.1.0

   8.11. Version 2.1.1

   8.12. Version 2.1.2

   8.13. Version 2.1.3

   8.14. Version 2.1.4

   8.15. Version 2.1.5

   8.16. Version 2.1.6

   8.17. Version 2.1.7

1. Wearables SDK overview

1.1. What is Wearables SDK?

The Wearables SDK is an SDK designed to integrate with Huawei's WearEngine, enabling direct communication between smartwatches and payment systems. It allows developers to create applications that support contactless payments directly from the watch, eliminating the need for a paired smartphone during transactions. This streamlined integration offers a secure and efficient way for users to make payments simply by wearing their smartwatch.

1.2. Versioning and backward compatibility

The SDK adheres to semantic versioning. For example 1.0.0 follows the MAJOR.MINOR.PATCH format.

• Major: A change in the major version indicates compatibility-breaking modifications to the SDK’s public APIs. When this number is incremented, updating the application code is mandatory.
• Minor: A change in the minor version represents the addition of new features or enhancements that do not break backward compatibility. Updating the application code is optional in this case.
• Patch: A change in the patch version covers internal modifications and bug fixes that have no impact on the public APIs. No application code changes are required when only this number is incremented.

Examples of backward-compatible changes include:

• adding a new optional interface to SDK setup
• introducing new methods in any domain
• adding new enum values for inputs or outputs
• incorporating new fields in input or output model

1.3 Prerequisites

Before integrating the Wearables SDK, ensure that your application properly handles user session and tokenization processes as these are essential components required for the Wearables SDK to function correctly. Most likely it would mean using our company's SDKs for those purposes - MDC SDK for session management and VCP SDK for payment token related processes. For more details please refer to VCP SDK and MDC SDK documentations.

For simplification further in the document both SDKs would be referred by generalized name as Session SDK and Tokenization SDK. However implementation examples would be provided with our company's default implementation in mind, showcasing code from MDC SDK and VCP SDK respectively.

2. Technical overview

This section provides basic information about the Wearables SDK setup and its available methods.

2.1. Basic information

2.1.1 Facade

The Facade serves as the entry point for communication with the Wearables SDK.

2.1.2 Multiple facade types

The Wearables SDK offers two sets of public APIs — one based on Kotlin coroutines and one using standard Java callbacks — each providing two distinct services:

• Coroutine Facade:

  • WearablesCoroutineService: manages communication with external devices
  • TokenCoroutineService: manages payment tokens
  • DevelopmentCoroutineService manages development tools

• Standard Facade:

  • WearablesStdService: manages communication with external devices
  • TokenStdService: manages payment tokens
  • DevelopmentStdService: manages development tools

Both facades use identical data models for inputs and outputs. This documentation presents I/O types in a Kotlin-centric style, which simplifies marking fields as nullable using the question mark syntax.

2.1.3 Method structure

Each method description follows the same structure:

Execution type:

• Asynchronous - the operation may take some time to complete and is executed on a background thread. The result is delivered via a callback
• Synchronous - the result of the operation is provided directly as the method’s return value

Method type:

• Online - the operation requires an Internet connection
• Offline - the operation can be executed without an Internet connection

Input
A list of parameters detailing their name, type, and description.

Output
For asynchronous methods, the output is delivered via a standard callback or, if using the coroutine-based API, returned as the result once the coroutine completes.

2.2 Basic configuration

2.2.1 Minimum SDK Version

The minimum required minSdkVersion is 26 (Android 8.0).

2.2.2 Artifactory

The SDK is hosted on the Verestro Maven repository and can be integrated using the Gradle build system. Note: The username and password for repository access are provided by Verestro.

repositories {
    maven {
        credentials {
            username "<enter_username_here>"
            password "<enter_password_here>"
        }
        url "https://artifactory.verestro.com/artifactory/android-release/"
    }
}  

2.2.3 SDK versions

The Wearables SDK is available in two variants: debug and release. The debug version is designed for development and debugging and its version name starts with the prefix "debug-". This version allows the application to run with an attached debugger. The release version is intended for production environments such as applications distributed via Google Play or Huawei AppGallery.

Release version:

dependencies {
    implementation 'com.verestro.sdk:wearables:{version}'
}  

Debug version:

dependencies {
    implementation 'com.verestro.sdk:wearables:debug-{version}'
}  

2.2.4 Source code obfuscation and optimization

Since the SDK is written in Kotlin, we recommend adding the following code to your Gradle configuration to support source code obfuscation and optimization:

android {
    ...
    kotlinOptions {
        freeCompilerArgs = [
                '-Xno-param-assertions',
                '-Xno-call-assertions',
                '-Xno-receiver-assertions'
        ]
    }
    packagingOptions { exclude '/kotlin_metadata/**' }
    ...
}  

Additionally, enable R8 in your gradle.properties file instead of ProGuard to leverage Google's latest tools for code shrinking, optimization, and obfuscation:

android.enableR8 = true  

2.2.5 Wearable app configuration

To integrate Wearables SDK into your wearable application, you must add your App ID to the manifestPlaceholders. This configuration is essential for ensuring that your application is correctly identified and authenticated by SDK.

manifestPlaceholders = [
        hmsClientAppId: "******"
]

Note: Replace ****** with the App ID generated when you created your app on the Huawei Developers portal.

2.3 Wearables SDK Setup

The Wearables SDK offers two primary configuration methods that initialize the necessary services for your application. Depending on your project requirements, you can choose between the Coroutine API and the Standard API.

• Coroutine API: Initialize using WearablesCoroutineApi.init(configuration: Configuration, providers: Providers).

• Standard API: Initialize using WearablesStdApi.init(configuration: Configuration, providers: Providers).

2.3.1 Input

Configuration

DeviceConfigurationModel

DeviceConfigurationModel.Huawei.Smart

DeviceConfigurationModel.Huawei.Sport

NOTE: *It is a Base64 representation of a Public Key of the certificate with which your Wearable App was signed. Most likely the certificate would be stored in your AppGallery Connect under: Certificates, app IDs, and profiles -> Certificates For more details how to retrieve appropriate fingerprint please refer to point 5 of HMS Core documentation.

Providers

ConnectionServiceNotificationBinder An interface that defines a method for binding a service to a foreground notification. Implementations of this interface handle the logic required to associate a service with a persistent notification, ensuring that the service operates in the foreground and remains visible to the user. This is particularly important for services that need to continue running even when the user is not interacting with the application.

class ConnectionServiceNotificationBinderImpl : ConnectionServiceNotificationBinder {

    override fun bind(
        intent: Intent?,
        service: Service
    ) {
        if (intent?.action != WATCH_SERVICE_NOTIFICATION) {
            runCatching {
                val notification = buildNotification()
                service.startForeground(NOTIFICATION_ID, notification)
            }
        }
    }

    private fun buildNotification(): Notification {
        val launchIntent = Intent(context, ApiConnectionService::class.java).apply {
            action = WATCH_SERVICE_NOTIFICATION
        }
        val pendingIntent = PendingIntent.getService(
            context,
            WATCH_NOTIFICATION_REQUEST_CODE,
            launchIntent,
            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
        )
        return NotificationCompat.Builder(context, channelId)
            .setContentIntent(pendingIntent)
            .build()
    }
}

ConnectionCallback An interface that provides callback methods to handle various connection events with a wearable device. Implementations of this interface define actions to be taken when the connection state changes, such as when a wearable device is connected, disconnected, or when the application on the wearable is not installed. These callbacks allow the application to respond appropriately to the current state of the wearable device connection.

TokenizationDataProvider An interface designed as a communication bridge obtaining necessary data during various processes happening in the scope of this SDK. Additionally, it triggers events in the mobile app as result of those processes whenever needed. Its purpose is to simplify integration of this SDK with mobile app (and Tokenization SDK within it) by limiting context required to be understood by an integrator, greatly facilitating the integration process and assuring correctness of implementation of required flows. To understand purpose of each method, possible situations in which particular method might be triggered and examples of how each method should be redirected to Tokenization SDK, please refer to separate section regarding this topic.

2.3.2 Available services

After initialization, each API exposes its services via lazy-loaded properties:

• WearablesCoroutineApi:

  • wearablesCoroutineService: manages communication with external devices
  • tokenCoroutineService: manages payment tokens
  • developmentCoroutineService: manages development tools

• WearablesStdApi:

  • wearablesStdService: manages communication with external devices
  • tokenStdService: manages payment tokens
  • developmentStdService: manages development tools

2.3.3 Sample

WearablesCoroutineApi

fun init(configuration: Configuration, providers: Providers) {
    WearablesCoroutineApi.init(configuration, providers)
}  

WearablesStdApi

fun init(configuration: Configuration, providers: Providers) {
    WearablesStdApi.init(configuration, providers)
}  

2.4 Integration tips

Before you begin integration with methods of this SDK it is beneficial to understand most crucial processes that are implemented in the scope of this SDK or require integrator's implementation, i.e.:

• what is ConnectionService responsible for and why it must be running whenever any communication between Mobile Phone App and Wearable App is being performed
• what are the steps required to successfully add payment token to wearable device
• how to assure continuity of payment functionality by regular data synchronization

2.5 Error handling

SDK returns errors by WearablesException, which could be caught by application and shown on UI with detailed message.
Table below describes general exception types.

WearablesException

3. Processes

3.1. Establishing connection

In order to establish and maintain connection between Mobile Phone App and Wearable App it is necessary to start ConnectionService which by design is a Foreground Service.

This SDK is tracking whether Mobile App is entering foreground state and automatically tries to start ConnectionService (as long as it is not already running). It is also possible to force ConnectionService to be started by invoking startConnectionService method.

It is crucial to assure that Service is running all the time, as it guarantees synchronization of data with Wearable App and assures continuity of wearable payments feature.

Since it is a Foreground Service it requires a Notification to which it is bound. Whenever this Service is started, ConnectionServiceNotificationBinder::bind method is invoked, within the scope of which integrator is obliged to provide system Notification. From ConnectionService perspective any standard Android Notification would suffice, so integrator of this SDK has freedom of choosing what it would look like. Very preliminary example of binding such Notification is given in Wearables SDK Setup section.

Any further communication with Wearable App (e.g. during syncing or adding token processes) requires ConnectionService up and running. That is why it is one of the most important elements integrator need to take care of.

NOTE: There is an alternative way of establishing connection only within certain CoroutineScope. It might be useful to assure connectivity during some short one-job operations (like adding card to the wearable device), but it cannot replace maintaining constant connection via ConnectionService. ConnectionService assures that whenever Wearable App requires new payment credentials they would be delivered as soon as possible.

3.2. Synchronization

Synchronization process is vital for ensuring enablement and continuity of payment functionality via wearable device. It consists of two stages:

• Pairing (Synchronization First Stage)
• Token Sync (Synchronization Second Stage)

The former is responsible for ensuring that all prerequisites necessary for further exchange of encrypted data are met.

The latter on the other hand is responsible for maintaining all data regarding tokens in sync with their state on the mobile phone app. This stage consists of:

• removing tokens no longer needed either on the wearable or the mobile
• updating state of the tokens remaining on the wearable whenever it differs from the one on the mobile
• triggering credentials replenish if their quantity fell below given threshold
• sending new payment credentials to the wearable device whenever they have been replenished

Synchronization process could be triggered either manually via syncStatus method or is triggered automatically by an app on wearable device whenever it is being opened or whenever payment has been finished.

Be aware that Synchronization First Stage is performed whenever synchronization is triggered. The Second Stage however would be performed immediately after First Stage is finished but only under condition that canPerformSync returns true. Said flag does not affect First Stage being performed thus it is perfectly correct to trigger synchronization with canPerformSync method returning true, as it would mean we deliberately want to trigger only First Stage of synchronization process.

IMPORTANT: Preventing Synchronization Second Stage from engaging is crucial in the process of adding new token to wearable device and is the sole purpose of the existence of the canPerformSync method. To understand why is it so, please refer to section regarding adding token topic.

For more details please refer to diagram below depicting whole synchronization process in more detail.

3.3. Adding token

Adding token is the process directly triggered by the user of the mobile phone app and could be divided into three steps:

• ensuring data required for encryption is exchanged between mobile and wearable device (this is tightly connected to Synchronization First Step)
• digitizing card which token would be transferred to wearable device
• sending said token and its credentials to wearable device

Each of these steps require invoking some methods either from Wearables SDK or Tokenization SDK in proper order. In case Verestro’s Tokenization SDK (VCP SDK) is used, it may also be necessary to await certain callbacks that are triggered in response to received push messages.

Exact step-by-step procedure of adding token based on use of our company's Tokenization SDK is depicted on the diagram below.

4. Wearables Service

4.1 startConnectionService

Synchronous. Offline. Requires connected wearable.

Initiates the connection service to establish communication with the wearable device. For further details regarding importance of said connection service please refer to this section.

4.1.1 Input

StartConnectionServiceData

4.1.2 Output

4.1.2.1 Success

Returns an StartConnectionServiceResult object upon successful initiation.

4.1.2.2 Failure

Failure callback with throwable.

Possible exceptions

4.1.3 Sample

Standard Callback

fun startConnectionService() {
    WearablesStdApi
        .wearablesStdService
        .startConnectionService(
            startConnectionServiceData = StartConnectionServiceData(forceStart = true),
            callback = object : ApiCallback<StartConnectionServiceResult> {
                override fun onSuccess(response: StartConnectionServiceResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun startConnectionService(): StartConnectionServiceResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .startConnectionService(
            startConnectionServiceData = StartConnectionServiceData(forceStart = true)
        ) 

4.2 stopConnectionService

Synchronous. Offline.

Stops the connection service used for establishing communication with the wearable device.

4.2.1 Input

StopConnectionServiceData

4.2.2 Output

4.2.2.1 Success

Returns an StopConnectionServiceResult object upon successful initiation.

4.2.2.2 Failure

Failure callback with throwable.

Possible exceptions

4.2.3 Sample

Standard Callback

fun stopConnectionService() {
    WearablesStdApi
        .wearablesStdService
        .stopConnectionService(
            stopConnectionServiceData = StopConnectionServiceData(forceStop = true),
            callback = object : ApiCallback<StopConnectionServiceResult> {
                override fun onSuccess(response: StopConnectionServiceResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun stopConnectionService(): StopConnectionServiceResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .stopConnectionService(
            stopConnectionServiceData = StopConnectionServiceData(forceStop = true)
        ) 

4.3 isConnectionServiceRunning

Synchronous. Offline.

Determines whether ConnectionService is currently running. It is based on internal tracker of activity of the process run in scope of this Service.

4.3.1 Input

None

4.3.2 Output

4.3.2.1 Success

Returns an IsConnectionServiceRunningResult object upon successful initiation.

IsConnectionServiceRunningResult

4.3.2.2 Failure

Failure callback with throwable.

Possible exceptions

4.3.3 Sample

Standard Callback

fun isConnectionServiceRunning() {
    WearablesStdApi
        .wearablesStdService
        .isConnectionServiceRunning(
            callback = object : ApiCallback<IsConnectionServiceRunningResult> {
                override fun onSuccess(response: IsConnectionServiceRunningResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun isConnectionServiceRunning(): IsConnectionServiceRunningResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .isConnectionServiceRunning() 

4.4 establishScopedConnection

Synchronous. Offline. Requires connected wearable.

It is an alternative way to establish connection with wearable in order to enable communication between Mobile App and Wearable App. Connection is maintained only as long as provided CoroutineScope is active, thus it significantly differs in comparison to starting ConnectionService - ConnectionService would maintain connection as long as it is allowed by the system. This method could be useful for performing short one-job operations in order to make sure that connection is maintained during those operations (e.g. adding card to the wearable device). For further details regarding establishing connection please refer to this section.

4.4.1 Input

EstablishScopedConnectionData

4.4.2 Output

4.4.2.1 Success

Returns an EstablishScopedConnectionResult object upon successful initiation.

EstablishScopedConnectionResult

4.4.2.2 Failure

Failure callback with throwable.

Possible exceptions

4.4.3 Sample

Standard Callback

fun establishScopedConnection(coroutineScope: CoroutineScope) {
    WearablesStdApi
        .wearablesStdService
        .establishScopedConnection(
            establishScopedConnectionData = EstablishScopedConnectionData(coroutineScope = coroutineScope),
            callback = object : ApiCallback<EstablishScopedConnectionResult> {
                override fun onSuccess(response: EstablishScopedConnectionResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun establishScopedConnection(coroutineScope: CoroutineScope): EstablishScopedConnectionResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .establishScopedConnection(
            establishScopedConnectionData = EstablishScopedConnectionData(coroutineScope = coroutineScope)
        ) 

4.5 getAvailableWearables

Asynchronous. Offline. Requires connected wearable.

Retrieves currently available wearable devices.

4.5.1 Input

None

4.5.2 Output

4.5.2.1 Success

Returns an GetAvailableWearablesResult object upon successful initiation.

GetAvailableWearablesResult

WearableModel

4.5.2.2 Failure

Failure callback with throwable.

Possible exceptions

4.5.3 Sample

Standard Callback

fun getAvailableWearables() {
    WearablesStdApi
        .wearablesStdService
        .getAvailableWearables(
            callback = object : ApiCallback<GetAvailableWearablesResult> {
                override fun onSuccess(response: GetAvailableWearablesResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun getAvailableWearables(): GetAvailableWearablesResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .getAvailableWearables() 

4.6 syncStatus

Asynchronous. Offline. Might require connected wearable.

Determines whether given wearable is connected (depending on connectionRequired parameter) and triggers synchronization process if possible. If connectionRequired is set to true, wearable would be automatically awaken trying to open the app in order to fully perform synchronization. If set to false, synchronization will be performed only if wearable is currently awaken and the app opened. As a result some basic information obtained from the wearable are being returned. Keep in mind that even though this method by itself does not require Internet connection, the synchronization process that might be triggered could invoke methods from TokenizationDataProvider which themselves could require Internet connection. For more information about synchronization process or TokenizationDataProvider methods please refer to sections regarding those topics.

4.6.1 Input

SyncStatusData

4.6.2 Output

4.6.2.1 Success

Returns an SyncStatusResult object upon successful initiation.

SyncStatusResult

4.6.2.2 Failure

Failure callback with throwable.

Possible exceptions

4.6.3 Sample

Standard Callback

fun syncStatus(syncStatusData: SyncStatusData) {
    WearablesStdApi
        .wearablesStdService
        .syncStatus(
            syncStatusData = syncStatusData,
            callback = object : ApiCallback<SyncStatusResult> {
                override fun onSuccess(response: SyncStatusResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun syncStatus(syncStatusData: SyncStatusData): SyncStatusResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .syncStatus(syncStatusData = syncStatusData)

4.7 registerConnectionCallback

Synchronous. Offline.

Registers ConnectionCallback.

4.7.1 Input

ConnectionCallback

4.7.2 Output

Returns an empty RegisterConnectionCallbackResult object.

Throws no exceptions.

4.7.3 Sample

Standard Callback

fun registerConnectionCallback(connectionCallback: ConnectionCallback) {
    WearablesStdApi
        .wearablesStdService
        .registerConnectionCallback(connectionCallback = connectionCallback)
}  

Kotlin Coroutines

suspend fun registerConnectionCallback(connectionCallback: ConnectionCallback) =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .registerConnectionCallback(connectionCallback)

4.8 unregisterConnectionCallback

Synchronous. Offline.

Unregisters ConnectionCallback.

4.8.1 Input

None

4.8.2 Output

Returns Unit.

Throws no exceptions.

4.8.3 Sample

Standard Callback

fun unregisterConnectionCallback() {
    WearablesStdApi
        .wearablesStdService
        .unregisterConnectionCallback()
}  

Kotlin Coroutines

suspend fun unregisterConnectionCallback() =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .unregisterConnectionCallback() 

4.9 registerReportingCallback

Synchronous. Offline.

Registers ReportingCallback.

4.9.1 Input

ReportingCallback

4.9.2 Output

Returns Unit.

Throws no exceptions.

4.9.3 Sample

Standard Callback

fun registerReportingCallback(reportingCallback: ReportingCallback) {
    WearablesStdApi
        .wearablesStdService
        .registerReportingCallback(reportingCallback = reportingCallback)
}  

Kotlin Coroutines

suspend fun registerReportingCallback(reportingCallback: ReportingCallback) =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .registerReportingCallback(reportingCallback)

4.10 unregisterReportingCallback

Synchronous. Offline.

Unregisters ReportingCallback.

4.10.1 Input

None

4.10.2 Output

Returns Unit.

Throws no exceptions.

4.10.3 Sample

Standard Callback

fun unregisterReportingCallback() {
    WearablesStdApi
        .wearablesStdService
        .unregisterReportingCallback()
}  

Kotlin Coroutines

suspend fun unregisterReportingCallback() =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .unregisterReportingCallback() 

4.11 unpairConnectedDevice

Synchronous. Offline. Requires connected wearable.

Removes all token and secure session related data from currently connected wearable. If no wearable is connected, this method won't have any effect. Since this method in a way resets wearable app to initial state when it comes to tokenized payment instruments it should be used in situations such as detection of security event or unpairing current user from mobile app. It is meant to make an attempt at preventing wearable user from further use of already tokenized payment instruments as such user is not authorized to use them anymore.

4.11.1 Input

None

4.11.2 Output

Returns an empty UnpairConnectedDeviceResult object.

Possible exceptions

4.11.3 Sample

Standard Callback

fun unpairConnectedDevice() {
    WearablesStdApi
        .wearablesStdService
        .unpairConnectedDevice(
            callback = object : ApiCallback<UnpairConnectedDeviceResult> {
                override fun onSuccess(response: UnpairConnectedDeviceResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun unpairConnectedDevice(): UnpairConnectedDeviceResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .unpairConnectedDevice()

4.12 isAppInstalledOnWearable

Synchronous. Offline. Requires connected wearable.

Determines whether companion app is installed on wearable. Wearable has to be connected to check the installation status.

4.12.1 Input

IsAppInstalledOnWearableData

4.12.2 Output

4.12.2.1 Success

Returns an IsAppInstalledOnWearableResult object upon successful initiation.

IsAppInstalledOnWearableResult

4.12.2.2 Failure

Failure callback with throwable.

Possible exceptions

4.12.3 Sample

Standard Callback

fun isAppInstalledOnWearable(isAppInstalledOnWearableData: IsAppInstalledOnWearableData) {
    WearablesStdApi
        .wearablesStdService
        .isAppInstalledOnWearable(
            isAppInstalledOnWearableData = isAppInstalledOnWearableData,
            callback = object : ApiCallback<IsAppInstalledOnWearableResult> {
                override fun onSuccess(response: IsAppInstalledOnWearableResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun isAppInstalledOnWearable(isAppInstalledOnWearableData: IsAppInstalledOnWearableData): IsAppInstalledOnWearableResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .isAppInstalledOnWearable(isAppInstalledOnWearableData = isAppInstalledOnWearableData)

5. Token Service

5.1 getWearablesIdsPairedWithToken

Asynchronous. Offline. Requires connected wearable.

Returns the identifiers of wearable devices paired with a specified payment token.

5.1.1 Input

GetWearablesIdsPairedWithTokenData

5.1.2 Output

5.1.2.1 Success

Returns an GetWearablesIdsPairedWithTokenResult object upon successful initiation.

GetWearablesIdsPairedWithTokenResult

5.1.2.2 Failure

Failure callback with throwable.

Possible exceptions

5.1.3 Sample

Standard Callback

fun getWearablesIdsPairedWithToken(getWearablesIdsPairedWithTokenData: GetWearablesIdsPairedWithTokenData) {
    WearablesStdApi
        .wearablesStdService
        .getWearablesIdsPairedWithToken(
            getWearablesIdsPairedWithTokenData = getWearablesIdsPairedWithTokenData,
            callback = object : ApiCallback<GetWearablesIdsPairedWithTokenResult> {
                override fun onSuccess(response: GetWearablesIdsPairedWithTokenResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun getWearablesIdsPairedWithToken(
    getWearablesIdsPairedWithTokenData: GetWearablesIdsPairedWithTokenData
): GetWearablesIdsPairedWithTokenResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .getWearablesIdsPairedWithToken(getWearablesIdsPairedWithTokenData = getWearablesIdsPairedWithTokenData) 

5.2 isWearablePairedWithToken

Synchronous. Offline.

Checks if a specific wearable device is paired with a given payment token.

5.2.1 Input

IsWearablePairedWithTokenData

5.2.2 Output

5.2.2.1 Success

Returns an IsWearablePairedWithTokenResult object upon successful initiation.

IsWearablePairedWithTokenResult

5.2.2.2 Failure

Failure callback with throwable.

Possible exceptions

5.2.3 Sample

Standard Callback

fun isWearablePairedWithToken(isWearablePairedWithTokenData: IsWearablePairedWithTokenData) {
    WearablesStdApi
        .wearablesStdService
        .isWearablePairedWithToken(
            isWearablePairedWithTokenData = isWearablePairedWithTokenData,
            callback = object : ApiCallback<IsWearablePairedWithTokenResult> {
                override fun onSuccess(response: IsWearablePairedWithTokenResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun isWearablePairedWithToken(
    isWearablePairedWithTokenData: IsWearablePairedWithTokenData
): IsWearablePairedWithTokenResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .isWearablePairedWithToken(isWearablePairedWithTokenData = isWearablePairedWithTokenData) 

5.3 removeToken

Asynchronous. Online.

Removes a specified payment instrument tokenization from mobile app and associated token from wearable, depending on whether wearableId is provided. If wearableId is provided, tokenization of payment instrument is being removed for specified wearable only (and if device is connected, associated token would be removed as well). If wearableId is not provided, tokenizations of this payment instrument for all wearable devices would be removed, removing associated tokens from currently connected wearable (if applicable).

5.3.1 Input

RemoveTokenData

5.3.2 Output

5.3.2.1 Success

Returns an RemoveTokenResult object upon successful initiation.

5.3.2.2 Failure

Failure callback with throwable.

Possible exceptions

5.3.3 Sample

Standard Callback

fun removeToken(removeTokenData: RemoveTokenData) {
    WearablesStdApi
        .wearablesStdService
        .removeToken(
            removeTokenData = removeTokenData,
            callback = object : ApiCallback<RemoveTokenResult> {
                override fun onSuccess(response: RemoveTokenResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun removeToken(removeTokenData: RemoveTokenData): RemoveTokenResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .removeToken(removeTokenData = removeTokenData) 

5.4 removeAllTokens

Asynchronous. Online.

Removes tokenizations of all payment instruments made for any wearable device. From the currently connected wearable it attempts to actually remove all added tokens as well.

5.4.1 Input

None

5.4.2 Output

5.4.2.1 Success

Returns an RemoveAllTokensResult object upon successful initiation.

5.4.2.2 Failure

Failure callback with throwable.

Possible exceptions

5.4.3 Sample

Standard Callback

fun removeAllTokens() {
    WearablesStdApi
        .wearablesStdService
        .removeAllTokens(
            callback = object : ApiCallback<RemoveAllTokensResult> {
                override fun onSuccess(response: RemoveAllTokensResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun removeAllTokens(): RemoveAllTokensResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .removeAllTokens() 

5.5 addToken

Asynchronous. Offline. Requires connected wearable.

Adds a new payment token to the wearable.

5.5.1 Input

AddTokenData

TokenModel

TokenType

TokenStatus

5.5.2 Output

5.5.2.1 Success

Returns an AddTokenResult object upon successful initiation.

5.5.2.2 Failure

Failure callback with throwable.

Possible exceptions

5.5.3 Sample

Standard Callback

fun addToken(addTokenData: AddTokenData) {
    WearablesStdApi
        .wearablesStdService
        .addToken(
            addTokenData = addTokenData,
            callback = object : ApiCallback<AddTokenResult> {
                override fun onSuccess(response: AddTokenResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun addToken(
    addTokenData: AddTokenData
): AddTokenResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .addToken(addTokenData = addTokenData) 

5.6 addTokenCredentials

Asynchronous. Offline. Requires connected wearable.

Adds credentials for a specified payment token.

5.6.1 Input

AddTokenCredentialsData

5.6.2 Output

5.6.2.1 Success

Returns an AddTokenCredentialsResult object upon successful initiation.

5.6.2.2 Failure

Failure callback with throwable.

Possible exceptions

5.6.3 Sample

Standard Callback

fun addTokenCredentials(addTokenCredentialsData: AddTokenCredentialsData) {
    WearablesStdApi
        .wearablesStdService
        .addTokenCredentials(
            addTokenCredentialsData = addTokenCredentialsData,
            callback = object : ApiCallback<AddTokenCredentialsResult> {
                override fun onSuccess(response: AddTokenCredentialsResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}  

Kotlin Coroutines

suspend fun addTokenCredentials(
    addTokenCredentialsData: AddTokenCredentialsData
): AddTokenCredentialsResult =
    WearablesCoroutineApi
        .wearablesCoroutineService
        .addTokenCredentials(addTokenCredentialsData = addTokenCredentialsData) 

5.7 handleTokenStatusChange

Asynchronous. Offline. Requires connected wearable.

Whenever status of a tokenized payment instrument changes, mobile application should receive push notification informing about such change. When it happens, it is necessary to reflect such change on wearable device to maintain proper functioning of contactless payments with this payment instrument. Most likely some kind of Tokenization SDK would wrap this push notification and provide callback informing about the change. Since in default implementation our company's Tokenization SDK would be used (VCP SDK), provided examples would be depicted as a reaction to particular event from UcpPaymentInstrumentEventListener in form of callback method. Please refer to VCP SDK documentation mentioned earlier in the document for more details. Keep in mind that even though invoking this method does not require Internet connection per se, it could trigger synchronization process which might require Internet connection after all.

5.7.1 Input

HandleTokenStatusChangeData

TokenStatus

5.7.2 Output

5.7.2.1 Success

Returns an HandleTokenStatusChangeResult object upon successful initiation.

5.7.2.2 Failure

Failure callback with throwable.

Possible exceptions

5.7.3 Sample

Standard Callback

override fun onPaymentInstrumentStatusChanged(event: EventPaymentInstrumentStatusChanged) {
    event.paymentDeviceId?.let { wearableId ->
        runCatching {
            WearablesStdApi.tokenStdService.handleTokenStatusChange(
                handleTokenStatusChangeData = HandleTokenStatusChangeData(
                    wearableId = wearableId,
                    paymentInstrumentId = event.paymentInstrumentId,
                    tokenStatus = TokenStatus(
                        value = when (event.newStatus) {
                            PaymentInstrumentStatus.ACTIVE -> TokenStatus.ACTIVE
                            PaymentInstrumentStatus.SUSPENDED -> TokenStatus.SUSPENDED
                            PaymentInstrumentStatus.DELETED,
                            PaymentInstrumentStatus.INACTIVE,
                            PaymentInstrumentStatus.UNKNOWN -> TokenStatus.DELETED
                        }
                    )
                ),
                callback = object : ApiCallback<HandleTokenStatusChangeResult> {
                    override fun onSuccess(response: HandleTokenStatusChangeResult) {
                        // handle success
                    }

                    override fun onFailure(error: Throwable) {
                        // handle error
                    }
                }
            )
        }
    }
}

Kotlin Coroutines

override fun onPaymentInstrumentStatusChanged(event: EventPaymentInstrumentStatusChanged) {
    event.paymentDeviceId?.let { wearableId ->
        runCatching {
            CoroutineScope(Dispatchers.IO + SupervisorJob()).launch {
                WearablesCoroutineApi.tokenCoroutineService.handleTokenStatusChange(
                    handleTokenStatusChangeData = HandleTokenStatusChangeData(
                        wearableId = wearableId,
                        paymentInstrumentId = event.paymentInstrumentId,
                        tokenStatus = TokenStatus(
                            value = when (event.newStatus) {
                                PaymentInstrumentStatus.ACTIVE -> TokenStatus.ACTIVE
                                PaymentInstrumentStatus.SUSPENDED -> TokenStatus.SUSPENDED
                                PaymentInstrumentStatus.DELETED,
                                PaymentInstrumentStatus.INACTIVE,
                                PaymentInstrumentStatus.UNKNOWN -> TokenStatus.DELETED
                            }
                        )
                    )
                )
            }
        }
    }
}

5.8 handleReplenishSuccess

Asynchronous. Offline. Requires connected wearable.

Whenever token credentials of a tokenized payment instrument are successfully replenished, mobile application should receive push notification informing about such event. When it happens, it is necessary to upload those credentials to wearable device in order to ensure payment feature continuity of affected payment instrument via wearable. Most likely some kind of Tokenization SDK would wrap this push notification and provide callback informing about the change. Since in default implementation our company's Tokenization SDK would be used (VCP SDK), provided examples would be depicted as a reaction to particular event from UcpPaymentInstrumentEventListener in form of callback method. Please refer to VCP SDK documentation mentioned earlier in the document for more details. Keep in mind that even though invoking this method does not require Internet connection per se, it could trigger synchronization process which might require Internet connection after all.

5.8.1 Input

HandleReplenishSuccessData

5.8.2 Output

5.8.2.1 Success

Returns an HandleReplenishSuccessData object upon successful initiation.

5.8.2.2 Failure

Failure callback with throwable.

Possible exceptions

5.8.3 Sample

Standard Callback

override fun onReplenishSuccess(event: EventReplenishSuccess) {
    event.paymentInstrument.paymentDeviceId?.let { wearableId ->
        WearablesStdApi.tokenStdService.handleReplenishSuccess(
            handleReplenishSuccessData = HandleReplenishSuccessData(
                wearableId = wearableId,
                paymentInstrumentId = event.paymentInstrument.id
            ),
            callback = object : ApiCallback<HandleReplenishSuccessResult> {
                override fun onSuccess(response: HandleReplenishSuccessResult) {
                    // handle success
                }

                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
    }
}

Kotlin Coroutines

override fun onReplenishSuccess(event: EventReplenishSuccess) {
    event.paymentInstrument.paymentDeviceId?.let { wearableId ->
        runCatching {
            CoroutineScope(Dispatchers.IO + SupervisorJob()).launch {
                WearablesCoroutineApi.tokenCoroutineService.handleReplenishSuccess(
                    handleReplenishSuccessData = HandleReplenishSuccessData(
                        wearableId = wearableId,
                        paymentInstrumentId = event.paymentInstrument.id
                    )
                )
            }
        }
    }
}

6. Development Service

This service and its methods are meant to be used only during development phase in order to ease debugging of potential issues. Due to that, none of the methods should be used in the final version of the app.

6.1 dumpLogs

Asynchronous. Offline. Requires connected wearable.

Returns logs from wearable.

6.1.1 Input

None

6.1.2 Output

6.1.2.1 Success

Returns a DumpLogsResult object upon successful initiation.

DumpLogsDetailsModel

6.1.2.2 Failure

Failure callback with throwable

6.1.3 Sample

Standard Callback

fun dumpLogs() {
    WearablesStdApi
        .developmentStdService
        .dumpLogs(
            callback = object : ApiCallback<DumpLogsResult> {
                override fun onSuccess(response: DumpLogsResult) {
                    //handle success
                }
                override fun onFailure(error: Throwable) {
                    //handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun dumpLogs(): DumpLogsResult =
    WearablesCoroutineApi
        .developmentCoroutineService
        .dumpLogs()

7. Interfaces requiring implementation

7.1. ReportingCallback

An interface which is designed to act as a conduit for transmitting event reports from the SDK to an external analytics tool. As the SDK executes its operations, various methods log events by creating instances of ReportModel and distributing those events via the onNewReport method.

7.1.1 onNewReport

Method invoked on any new event that occurred in SDK that might be reported. Events that might be reported are listed in section regarding this topic.

In default implementation using our company's SDKs events should be forwarded to the MDC SDK via the onNewReport(...) function of ReportsModuleApi object as in the example below. This mechanism ensures that every significant action within the SDK is captured and easily traceable in the logs, facilitating efficient debugging, monitoring, and auditing of the system's behavior.

7.1.1.1 Input

OnNewReportData

ReportModel.Event

ReportModel.Error

7.1.1.2 Output

Returns an empty OnNewReportResult object.

7.1.1.3 Sample

Standard Callback

override fun onNewReport(onNewReportData: OnNewReportData): OnNewReportResult {
    ReportsModuleApi.onNewReport(
        newEvent = NewEvent(
            name = onNewReportData.report.name,
            description = onNewReportData.report.description,
            isSuccess = onNewReportData.report !is ReportModel.Error,
            exception = (onNewReportData.report as? ReportModel.Error)
                ?.exception?.let { exception -> Exception(exception) },
            errorMessage = (onNewReportData.report as? ReportModel.Error)?.exception?.message,
            timestamp = onNewReportData.report.timestamp,
            params = onNewReportData.report.params,
            card = NewEventCard(
                cardId = onNewReportData.report.paymentInstrumentId,
                lastFourDigits = null
            )
        )
    )
    return OnNewReportResult()
}

7.1.2 Report categories

Events or errors that might occur while SDK is executing its operations are categorized by name field of ReportModel and could be as follows:

To fully understand the nature of those events it might be necessary to acknowledge main process that this SDK is responsible for in section regarding that topic.

7.2 ConnectionCallback

An interface informing about changes in connection state with wearable devices.

7.2.1 onConnectionMonitorRegistered

Method informing that internal process that monitors connection with wearable devices was registered.

7.2.1.1 Input

None

7.2.1.2 Output

Returns an empty OnConnectionMonitorRegisteredResult object.

7.2.1.3 Sample

Standard Callback

override fun onConnectionMonitorRegistered(): OnConnectionMonitorRegisteredResult {
    //handle event
    return OnConnectionMonitorRegisteredResult()
}

7.2.2 onConnected

Method informing that particular wearable has been connected.

7.2.2.1 Input

OnConnectedData

WearableModel

7.2.2.2 Output

Returns an empty OnConnectedResult object.

7.2.2.3 Sample

Standard Callback

override fun onConnected(onConnectedData: OnConnectedData): OnConnectedResult {
    //handle event
    return OnConnectedResult()
}

7.2.3 onDisconnected

Method informing that particular wearable has been disconnected.

7.2.3.1 Input

OnDisconnectedData

WearableModel

7.2.3.2 Output

Returns an empty OnDisconnectedResult object.

7.2.3.3 Sample

Standard Callback

override fun onDisconnected(onDisconnectedData: OnDisconnectedData): OnDisconnectedResult {
    //handle event
    return OnDisconnectedResult()
}

7.2.4 onAppNotInstalled

Method informing that wearable that has established connection is missing an app equivalent of mobile app. In this case app on wearable should be installed.

7.2.4.1 Input

OnAppNotInstalledData

WearableModel

7.2.4.2 Output

Returns an empty OnAppNotInstalledResult object.

7.2.4.3 Sample

Standard Callback

override fun onAppNotInstalled(onAppNotInstalledData: OnAppNotInstalledData): OnAppNotInstalledResult {
    //handle event
    return OnAppNotInstalledResult()
}

7.3 TokenizationDataProvider

As mentioned earlier in this document, sole purpose of this interface is to create a bridge providing necessary data whenever it is needed by internal processes being handled by Wearables SDK Keep in mind that most of the methods could be triggered at any given moment. It is due to the fact that they might not be directly connected with logic underneath any facade method of this SDK executed from the code of the mobile app.

To understand in more detail when execution of particular methods can be expected, please refer to section showcasing most important processes of this SDK step by step.

When implemented, each method should redirect to its equivalent in Tokenization SDK, and since most probably SDK used for that purpose would be our company's own VCP SDK all the examples would be based on redirecting to its appropriate method.

7.3.1 createSecureSession

Method that creates RSA keys for secure communication and returns session data required for further exchange of sensitive data (such as token or its credentials) in a secure way. This method is being invoked by this SDK as a part of processes of adding token and synchronization, and to function properly it is required that device pairing is performed beforehand.

7.3.1.1 Input

CreateSecureSessionData

7.3.1.2 Output

7.3.1.2.1 Success

Returns a CreateSecureSessionResult object upon successful initiation.

7.3.1.2.2 Failure

Failure callback with throwable

7.3.1.3 Sample

Standard Callback

override fun createSecureSession(
    createSecureSessionData: CreateSecureSessionData,
    callback: ApiCallback<CreateSecureSessionResult>
) {
    UcpApiKotlin().tokenService.createSecureSession(
        createSecureSession = CreateSecureSession(paymentDeviceId = createSecureSessionData.wearableId),
        success = { result ->
            callback.onSuccess(
                CreateSecureSessionResult(secureSessionData = result.secureSessionData)
            )
        },
        failure = callback::onFailure
    )
}

7.3.2 getEncryptedToken

Method that obtains encrypted token data of a particular payment instrument digitized for a particular wearable device. This method is being invoked by this SDK as a part of process of adding token and uses secure session data obtained from createSecureSession method.

7.3.2.1 Input

GetEncryptedTokenData

7.3.2.2 Output

7.3.2.2.1 Success

Returns a GetEncryptedTokenResult object upon successful initiation.

7.3.2.2.2 Failure

Failure callback with throwable

7.3.2.3 Sample

Standard Callback

override fun getEncryptedToken(
    getEncryptedTokenData: GetEncryptedTokenData,
    callback: ApiCallback<GetEncryptedTokenResult>
) {
    UcpApiKotlin().tokenService.getTokenProfile(
        getTokenProfile = GetTokenProfile(
            paymentDeviceId = getEncryptedTokenData.wearableId,
            paymentInstrumentId = getEncryptedTokenData.paymentInstrumentId,
            secureSessionData = getEncryptedTokenData.secureSessionData
        ),
        success = { result ->
            callback.onSuccess(
                GetEncryptedTokenResult(encryptedToken = result.payload)
            )
        },
        failure = callback::onFailure
    )
}

7.3.3 getEncryptedTokenTransactionCredentials

Method that obtains encrypted transaction credentials data of a particular token. This method is being invoked by this SDK as a part of processes of adding token and synchronization, and uses secure session data obtained from createSecureSession method.

7.3.3.1 Input

GetEncryptedTokenTransactionCredentialsData

7.3.3.2 Output

7.3.3.2.1 Success

Returns a GetEncryptedTokenTransactionCredentialsResult object upon successful initiation.

7.3.3.2.2 Failure

Failure callback with throwable

7.3.3.3 Sample

Standard Callback

override fun getEncryptedTokenTransactionCredentials(
    getEncryptedTokenTransactionCredentialsData: GetEncryptedTokenTransactionCredentialsData,
    callback: ApiCallback<GetEncryptedTokenTransactionCredentialsResult>
) {
    UcpApiKotlin().tokenService.getTokenCredentials(
        getTokenCredentials = GetTokenCredentials(
            paymentDeviceId = getEncryptedTokenTransactionCredentialsData.wearableId,
            paymentInstrumentId = getEncryptedTokenTransactionCredentialsData.paymentInstrumentId,
            secureSessionData = getEncryptedTokenTransactionCredentialsData.secureSessionData
        ),
        success = { result ->
            callback.onSuccess(
                GetEncryptedTokenTransactionCredentialsResult(encryptedTokenTransactionCredentials = result.payload)
            )
        },
        failure = callback::onFailure
    )
}

7.3.4 updateTokenCredentials

Method that provides current status of transaction credentials to mobile app in order to keep information between devices up to date. It is crucial in determining whether replenishing new credentials is needed, thus ensuring continuity of availability of standalone payment feature by wearable device whenever needed. This method is being invoked by this SDK as a part of process of synchronization.

7.3.4.1 Input

UpdateTokenCredentialsData

7.3.4.2 Output

7.3.4.2.1 Success

Returns an UpdateTokenCredentialsResult object upon successful initiation.

7.3.4.2.2 Failure

Failure callback with throwable

7.3.4.3 Sample

Standard Callback

override fun updateTokenCredentials(
    updateTokenCredentialsData: UpdateTokenCredentialsData,
    callback: ApiCallback<UpdateTokenCredentialsResult>
) {
    UcpApiKotlin().tokenService.updateTokenCredentials(
        updateTokenCredentials = UpdateTokenCredentials(
            paymentDeviceId = updateTokenCredentialsData.wearableId,
            updateTokenCredentials = updateTokenCredentialsData.usedCredentialsInfo
        ),
        success = { _ ->
            callback.onSuccess(
                UpdateTokenCredentialsResult()
            )
        },
        failure = callback::onFailure
    )
}

7.3.5 getTokenizedPaymentInstruments

Method that obtains current state of tokenized payment instruments from mobile app, either for particular wearable (if wearableId parameter is provided) or all wearables for which tokenization was performed. This method is being invoked by this SDK as part of various internal processes, e.g. synchronization, thus it might be invoked frequently.

7.3.5.1 Input

GetTokenizedPaymentInstrumentsData

7.3.5.2 Output

7.3.5.2.1 Success

Returns a GetTokenizedPaymentInstrumentsResult object upon successful initiation.

TokenizedPaymentInstrumentModel

TokenStatus

7.3.5.2.2 Failure

Failure callback with throwable

7.3.5.3 Sample

Standard Callback

override fun getTokenizedPaymentInstruments(
    getTokenizedPaymentInstrumentsData: GetTokenizedPaymentInstrumentsData,
    callback: ApiCallback<GetTokenizedPaymentInstrumentsResult>
) {
    UcpApiKotlin().cardsService.getAllPaymentInstruments(
        getAllPaymentInstruments = GetAllPaymentInstruments(
            refresh = false
        ).apply {
            searchForDefaultPaymentDeviceOnly = false
        },
        success = { result ->
            runCatching {
                result.filter { paymentInstrument ->
                    paymentInstrument.paymentDeviceId == getTokenizedPaymentInstrumentsData.wearableId
                }.map { paymentInstrument ->
                    TokenizedPaymentInstrumentModel(
                        paymentInstrumentId = paymentInstrument.id,
                        paymentTokenId = paymentInstrument.paymentTokenId,
                        credentialsCount = paymentInstrument.credentialsCount,
                        status = TokenStatus(
                            value = when (paymentInstrument.status) {
                                PaymentInstrumentStatus.ACTIVE -> TokenStatus.ACTIVE
                                PaymentInstrumentStatus.SUSPENDED -> TokenStatus.SUSPENDED
                                PaymentInstrumentStatus.DELETED,
                                PaymentInstrumentStatus.INACTIVE,
                                PaymentInstrumentStatus.UNKNOWN -> TokenStatus.DELETED
                            }
                        )
                    )
                }.let { tokenizedPaymentInstrument ->
                    callback.onSuccess(
                        GetTokenizedPaymentInstrumentsResult(paymentInstruments = tokenizedPaymentInstrument)
                    )
                }
            }.onFailure { error ->
                callback.onFailure(error = error)
            }
        },
        failure = callback::onFailure
    )
}

7.3.6 triggerCredentialsReplenish

Method that triggers replenish of transaction credentials on mobile app. It might be triggered whenever this SDK determines that amount of remaining token credentials for particular token is below given threshold as set in configuration. This method might be invoked by this SDK as a part of process of synchronization.

7.3.6.1 Input

TriggerCredentialsReplenishData

7.3.6.2 Output

7.3.6.2.1 Success

Returns a TriggerCredentialsReplenishResult object upon successful initiation.

7.3.6.2.2 Failure

Failure callback with throwable

7.3.6.3 Sample

Standard Callback

override fun triggerCredentialsReplenish(
    triggerCredentialsReplenishData: TriggerCredentialsReplenishData,
    callback: ApiCallback<TriggerCredentialsReplenishResult>
) {
    UcpApiKotlin().paymentService.replenishCredentials(
        replenishCredentials = ReplenishCredentials(
            paymentInstrumentId = triggerCredentialsReplenishData.paymentInstrumentId
        ).apply { this.paymentDeviceId = triggerCredentialsReplenishData.wearableId },
        success = {
            callback.onSuccess(
                TriggerCredentialsReplenishResult()
            )
        },
        failure = callback::onFailure
    )
}

7.3.7 deleteTokenizedPaymentInstrument

Method that deletes tokenization of particular payment instrument for particular wearable device. Should be used whenever it is no longer necessary to keep such a tokenization. This method might be invoked by this SDK as a part of process of synchronization as well as triggered as a part of logic behind such methods as removeToken or removeAllTokens.

7.3.7.1 Input

DeleteTokenizedPaymentInstrumentData

7.3.7.2 Output

7.3.7.2.1 Success

Returns a DeleteTokenizedPaymentInstrumentResult object upon successful initiation.

7.3.7.2.2 Failure

Failure callback with throwable

7.3.7.3 Sample

Standard Callback

override fun deleteTokenizedPaymentInstrument(
    deleteTokenizedPaymentInstrumentData: DeleteTokenizedPaymentInstrumentData,
    callback: ApiCallback<DeleteTokenizedPaymentInstrumentResult>
) {
    UcpApiKotlin().cardsService.delete(
        deleteCard = DeleteCard(
            paymentInstrumentId = deleteTokenizedPaymentInstrumentData.paymentInstrumentId,
            reason = null
        ).apply { this.paymentDeviceId = deleteTokenizedPaymentInstrumentData.wearableId },
        success = {
            callback.onSuccess(
                DeleteTokenizedPaymentInstrumentResult()
            )
        },
        failure = callback::onFailure
    )
}

7.3.8 pairDevice

Method that passes necessary data (i.e. RSA public key) obtained during synchronization of an unpaired wearable device to mobile app in order to ensure future successful creation of secure session whenever needed. This method might be triggered each time during synchronization, as long as device is not fully paired, which will happen with first creation of secure session.

7.3.8.1 Input

PairDeviceData

7.3.8.2 Output

7.3.8.2.1 Success

Returns a PairDeviceResult object upon successful initiation.

7.3.8.2.2 Failure

Failure callback with throwable

7.3.8.3 Sample

Standard Callback

override fun pairDevice(
    pairDeviceData: PairDeviceData,
    callback: ApiCallback<PairDeviceResult>
) {
    UcpApiKotlin().tokenService.pairDevice(
        pairExternalDevice = PairExternalDevice(
            paymentDeviceId = pairDeviceData.wearableId,
            pairDeviceData = pairDeviceData.pairDeviceData
        ),
        success = {
            callback.onSuccess(
                PairDeviceResult()
            )
        },
        failure = callback::onFailure
    )
}

7.3.9 isDevicePaired

Determines whether mobile app has already registered this wearable device as paired. It is verified as a part of synchronization process and might result in further unpairing of such wearable when the states on both devices (mobile and wearable) do not match. This would trigger synchronization process from the beginning.

7.3.9.1 Input

IsDevicePairedData

7.3.9.2 Output

7.3.9.2.1 Success

Returns an IsDevicePairedResult object upon successful initiation.

7.3.9.2.2 Failure

Failure callback with throwable

7.3.9.3 Sample

Standard Callback

override fun isDevicePaired(
    isDevicePairedData: IsDevicePairedData,
    callback: ApiCallback<IsDevicePairedResult>
) {
    UcpApiKotlin().tokenService.getExternalDeviceStatus(
        getExternalDeviceStatus = GetExternalDeviceStatus(
            paymentDeviceId = isDevicePairedData.wearableId
        ),
        success = { result ->
            callback.onSuccess(
                IsDevicePairedResult(isDevicePaired = result.devicePairedInSdk)
            )
        },
        failure = callback::onFailure
    )
}

7.4 ConsentProvider

An interface designed to allow internal processes of this SDK to obtain information whether some procedures might be initiated at any given moment. It is necessary due to the fact that performing some processes externally (via API methods available in this SDK's services) and internally (via internal triggers) at the same time might cause unexpected and hard to control results.

7.4.1 canPerformSync

Asynchronous. Offline.

Gives SDK information whether it is allowed to start synchronization process when its internal processes are trying to trigger such synchronization at that particular moment. The purpose of this method is to block any possible interception with multi-level process of adding payment instrument token to wearable device. It is necessary due to the fact that interruption of said process at any given moment would result in the whole process being dismissed and would require it to be performed once again. For more details please refer to adding token process section as it is especially prone to errors when intercepted, since it generates data states unexpected outside of this process as well as sends data to wearable partially (thus data might be incomplete in the meantime). Outside of said process it is allowed to perform sync, so canPerformSync should be implemented in a way that most of the time returns true value.

7.4.1.1 Input

None

7.4.1.2 Output

7.4.1.2.1 Success

Returns a CanPerformSyncResult object upon successful initiation.

7.4.1.2.2 Failure

Failure callback with throwable

7.4.1.3 Sample

Standard Callback

override fun canPerformSync() {
    val canPerformSync =
        true //determine whether user is not in the middle of the process of adding new card to wearable device
    return CanPerformSyncResult(canPerformSync = canPerformSync)
}

7.4.2 canAutomaticallyStartConnectionService

Asynchronous. Offline.

Determines whether ConnectionService can be automatically started whenever mobile app appears in the foreground. ConnectionService will no be restarted if it is already up and running.

7.4.2.1 Input

None

7.4.2.2 Output

7.4.2.2.1 Success

Returns a CanAutomaticallyStartConnectionServiceResult object upon successful initiation.

7.4.2.2.2 Failure

Failure callback with throwable

7.4.2.3 Sample

Standard Callback

override fun canAutomaticallyStartConnectionService() =
    CanAutomaticallyStartConnectionServiceResult(canAutomaticallyStartConnectionService = true)

7.5 TokenCallback

An interface intended for providing information about the token state. It allows monitoring changes in the token lifecycle and reacting to events related to its handling.

7.5.1 onCredentialsAdded

A method designed to provide information about the result of adding a token. It allows the SDK to notify whether the token has been successfully added, ensuring that the application can react accordingly.

Asynchronous. Offline.

7.5.1.1 Input

OnCredentialsAddedData

7.5.1.2 Output

Returns an empty OnCredentialsAddedResult object.

7.5.1.3 Sample

Standard Callback

override fun onCredentialsAdded(onCredentialsAddedData: OnCredentialsAddedData): OnCredentialsAddedResult {
    //handle event
    return OnCredentialsAddedResult()
}

8. Document changelog

8.1. Version 1.1.3

• Created Wearables SDK.

8.2. Version 1.1.4

• Made HceApduHandler nullable since it is deprecated as a part of payment method no longer supported.

8.3. Version 1.1.5

• Internal changes improving SDK delivery process.

8.4. Version 1.1.6

• Internal changes improving SDK delivery process.

8.5. Version 1.1.7

• Internal, not functional improvements.

8.6. Version 1.1.8

• Added TokenCallback with method onCredentialsAdded.

8.7. Version 1.1.9

• Added diagrams to adding token and syncing data processes.

8.8. Version 2.0.0

• Aggregated facade errors. Updated errors description in documentation.

8.9. Version 2.0.1

• Fixed internal crash, which appeared in 2.0.0.

8.10. Version 2.1.0

• Deprecated parameterless startConnectionService method
• Added new methods for greater control of ConnectionService, i.e. startConnectionService, stopConnectionService, isConnectionServiceRunning
• Added new method for establishing scoped connection for short operations - establishScopedConnection
• Made SDK aware of application process Lifecycle in order to automatically start ConnectionService whenever app goes to the foreground
• Added new method to the ConsentProvider interface - canAutomaticallyStartConnectionService. It needs to be overridden in order to enable automatic start of ConnectionService whenever mobile app enters foreground.

8.11. Version 2.1.1

• Fixed internal build issue.

8.12. Version 2.1.2

• Added deviceModel field to WearableModel.

8.13. Version 2.1.3

• Added isAppInstalledOnWearable method to Wearables Service facade.

8.14. Version 2.1.4

• Internal changes. Adds unregister receiver data.

8.15. Version 2.1.5

• Fixed internal issue that caused application crash in certain specific circumstances

8.16. Version 2.1.6

• Added onUnsupportedDeviceType callback.

8.17. Version 2.1.7

• Internal. Updates build utilities.