Wearables SDK
Version 2.1.10
Table of Contents
-
1.2. Versioning and backward compatibility
1.3. Prerequisites
-
2.1. Basic information
2.2. Basic configuration
2.3. Wearables SDK Setup
2.4. Integration tips
2.5. Error handling
-
3.2 Synchronization
3.3 Adding token
-
4.3. isConnectionServiceRunning
4.4. establishScopedConnection
4.6. syncStatus
4.7. registerConnectionCallback
4.8. unregisterConnectionCallback
4.9. registerReportingCallback
4.10. unregisterReportingCallback
4.11. unpairConnectedDevice
4.12. isAppInstalledOnWearable
-
5.1. getWearablesIdsPairedWithToken
5.2. isWearablePairedWithToken
5.3. removeToken
5.4. removeAllTokens
5.5. addToken
5.6. addTokenCredentials
-
6.1 dumpLogs
Interfaces requiring implementation
7.1.1 onNewReport
7.1.2 Report categories
7.2.1 onConnectionMonitorRegistered
7.2.2 onConnected
7.2.3 onDisconnected
7.2.4 onAppNotInstalled
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.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
8.18. Version 2.1.8
8.19. Version 2.1.9
8.20. Version 2.1.10
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
| Parameter | Type | Description |
|---|---|---|
| application | Application | The base Android Application instance. |
| deviceConfigurations | List<DeviceConfigurationModel> | List of configurations per type of wearable supported by the app |
| appVersion | String | The version of your mobile application. |
| replenishThreshold | Int | Token threshold below which replenish should be performed. |
| connectionServiceNotificationBinder | ConnectionServiceNotificationBinder | An interface responsible for binding notifications. |
DeviceConfigurationModel
| Type | Description |
|---|---|
| DeviceConfigurationModel.Huawei.Smart | Configuration for Huawei Smart type wearable |
| DeviceConfigurationModel.Huawei.Sport | Configuration for Huawei Sport type wearable |
DeviceConfigurationModel.Huawei.Smart
| Parameter | Type | Description |
|---|---|---|
| bundleId | String | Package Name field that could be found on your HarmonyOS app page on AppGallery Connect in: App information -> Basic information -> Package name |
| fingerprint | String | App ID field that could be found on your HarmonyOS app page on AppGallery Connect in: App information -> Basic information -> App ID |
DeviceConfigurationModel.Huawei.Sport
| Parameter | Type | Description |
|---|---|---|
| bundleId | String | Package Name field that could be found on your HarmonyOS app page on AppGallery Connect in: App information -> Basic information -> Package name |
| fingerprint | String | The fingerprint of certificate with which your Wearable App was signed.* |
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
| Parameter | Type | Description |
|---|---|---|
| tokenizationDataProvider | TokenizationDataProvider | Provider used for exchanging data with Tokenization SDK. |
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
- wearablesCoroutineService: manages communication with external devices
WearablesStdApi:
- wearablesStdService: manages communication with external devices
- tokenStdService: manages payment tokens
- developmentStdService: manages development tools
- wearablesStdService: manages communication with external devices
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
| Exception | Description | Suggested handling |
|---|---|---|
| AppNotRunning | The wearable application is not running on the wearable device. | Show information indicating that the application must be opened on the wearable device. |
| AppNotInstalled | The wearable application is not installed on the wearable device. | Show information indicating that the application must be installed on the wearable device. |
| EcosystemNotInstalled | The required ecosystem applications/services are not installed on the mobile device. | Show information indicating that the ecosystem must be installed on the mobile device. |
| CommunicationFailed | Communication with wearable device's application has been lost. | Show information indicating the communication issue and try again. |
| DeviceInactiveError | Wearable device is sleeping/inactive. | Show information indicating that the device must be woken up on the wearable device. |
| WearableNotFound | The given wearable couldn't be found among bounded devices. | Depending on the scenario, show information to pair the wearable device or try with another one. |
| WearableNotConnected | No active connection to the wearable device. | Depending on scenario, show information indicating connection issue and retry or try with another wearable device. |
| WearableAppError | An error has occurred in the wearable application. | Show information indicating the issue on wearable app or device and try again. |
| WearableAppBusy | The wearable application is processing some operation and cannot handle requests at the moment. | Show information indicating the progress on wearable app and try again. |
| ReachedTimeout | Operation exceeded the allowed time limit. | Show information indicating the timeout issue and try again. |
| RequestCancelledException | Request has been cancelled before completion. | Depending on the scenario, try again or ignore. |
| ProcessFailed | An initiated process has failed due to technical reasons. Check cause error. | Show information indicating the technical issue and try again. |
| NetworkConnectionException | Failed to connect to the server. | Show information indicating the network issue and try again. |
| SdkNotInitialized | SDK has been accessed before init was called. Carries origin indicating the entry point. |
Make sure WearablesStdApi.init / WearablesCoroutineApi.init is called before any service or ConnectionService usage. |
| MissingDefinition | Internal Koin definition could not be resolved. Most likely indicates that SDK was not initialized. | Make sure init has been called; inspect cause for the underlying error. |
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) requiresConnectionService 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.
Init prerequisite: ConnectionService is an additional entry point to the SDK and relies on
internal components that are wired only after WearablesStdApi.init orWearablesCoroutineApi.init has been called. Starting the Service before SDK initialization is
a no-op — the Service stops itself immediately.
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
| Parameter | Type | Description |
|---|---|---|
| forceStart | Boolean | Flag determining whether ConnectionService would be restarted in case it's already running. |
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
| Exception |
|---|
| RequestCancelledException |
| EcosystemNotInstalled |
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`**
| Parameter | Type | Description |
|-----------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| forceStop | Boolean | Flag determining whether ConnectionService would be stoped even though internal tracker of its state informs that it's not currently running. |
#### 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`**
| Exception |
|---------------------------|
| RequestCancelledException |
#### 4.2.3 Sample
**`Standard Callback`**
```kotlin
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`**
| Parameter | Type | Description |
|-----------|---------|-------------------------------------------------------------------------------------------------------------|
| isRunning | Boolean | Flag determining whether ConnectionService is currently running according to internal tracker of its state. |
##### 4.3.2.2 Failure
Failure callback with throwable.
**`Possible exceptions`**
| Exception |
|---------------------------|
| RequestCancelledException |
#### 4.3.3 Sample
**`Standard Callback`**
```kotlin
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](#41-startconnectionservice) -
`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](#31-establishing-connection) section.
#### 4.4.1 Input
**`EstablishScopedConnectionData`**
| Parameter | Type | Description |
|----------------|----------------|--------------------------------------------------------------------------------------------------------|
| coroutineScope | CoroutineScope | Scope of the Kotlin coroutine withing which the connection would be established (e.g. viewModelScope). |
#### 4.4.2 Output
##### 4.4.2.1 Success
Returns an `EstablishScopedConnectionResult` object upon successful initiation.
**`EstablishScopedConnectionResult`**
| Parameter | Type | Description |
|---------------------|------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| scopedConnectionJob | Job | Kotlin coroutines Job associated with established connection process. It could be used to stop the connection whenever needed, without waiting for CoroutineScope within which the process is running to be stopped. |
##### 4.4.2.2 Failure
Failure callback with throwable.
**`Possible exceptions`**
| Exception |
|---------------------------|
| RequestCancelledException |
#### 4.4.3 Sample
**`Standard Callback`**
```kotlin
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`**
| Parameter | Type | Description |
|-----------|-----------------------|------------------------------|
| wearables | List\<WearableModel\> | List of available wearables. |
**`WearableModel`**
| Parameter | Type | Description |
|-----------------|----------------|-----------------------------------------------|
| id | String | Identifier of the wearable. |
| name | String | Name of the wearable. |
| softwareVersion | String | Software version of the wearable. |
| isConnected | Boolean | Defines whether the wearable is connected. |
| pairedTokensIds | List\<String\> | List of ids of paired tokens. |
| deviceModel | String | Model of the device provided by the producer. |
##### 4.5.2.2 Failure
Failure callback with throwable.
**`Possible exceptions`**
| Exception |
|---------------------------|
| RequestCancelledException |
| ProcessFailed |
#### 4.5.3 Sample
**`Standard Callback`**
```kotlin
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](#32-synchronization)
or [TokenizationDataProvider methods](#73-tokenizationdataprovider) please refer to sections
regarding those topics.
#### 4.6.1 Input
**`SyncStatusData`**
| Parameter | Type | Description |
|--------------------|---------|-------------------------------------------------------------------------------------|
| wearableId | String | Wearable identifier. |
| connectionRequired | Boolean | Flag determining whether wearable should get awaken and app opened to perform sync. |
#### 4.6.2 Output
##### 4.6.2.1 Success
Returns an `SyncStatusResult` object upon successful initiation.
**`SyncStatusResult`**
| Parameter | Type | Description |
|------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| appVersion | String? | Version of the app installed on the wearable. Might be useful in determining whether wearable app supports certain features. If returned value is null it means wearable app is not yet supporting returning its own version number. |
| sdkVersion | String? | Wearable app might utilize some SDKs underneath. If so, versions of particular SDKs should be returned. In default implementation using our company's own SDKs facilitating wearable app development, versions of those SDKs would be returned. If returned value is null it means wearable app is not yet supporting returning those version numbers or there are no SDKs used underneath. |
##### 4.6.2.2 Failure
Failure callback with throwable.
**`Possible exceptions`**
| Exception |
|---------------------------|
| RequestCancelledException |
| ProcessFailed |
| CommunicationFailed |
| AppNotInstalled |
| WearableAppError |
| WearableAppBusy |
| DeviceInactiveError |
| ReachedTimeout |
| WearableNotFound |
| WearableNotConnected |
| AppNotRunning |
#### 4.6.3 Sample
**`Standard Callback`**
```kotlin
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](#72-connectioncallback).
#### 4.7.1 Input
**`ConnectionCallback`**
| Parameter | Type | Description |
|--------------------|--------------------|-----------------------------------------------------|
| connectionCallback | ConnectionCallback | Implementation of the ConnectionCallback interface. |
#### 4.7.2 Output
Returns an empty `RegisterConnectionCallbackResult` object.
Throws no exceptions.
#### 4.7.3 Sample
**`Standard Callback`**
```kotlin
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](#72-connectioncallback).
#### 4.8.1 Input
None
#### 4.8.2 Output
Returns `Unit`.
Throws no exceptions.
#### 4.8.3 Sample
**`Standard Callback`**
```kotlin
fun unregisterConnectionCallback() {
WearablesStdApi .wearablesStdService .unregisterConnectionCallback()} Kotlin Coroutines
suspend fun unregisterConnectionCallback() =
WearablesCoroutineApi .wearablesCoroutineService .unregisterConnectionCallback() ```
### 4.9 registerReportingCallback
Synchronous. Offline.
Registers [ReportingCallback](#71-reportingcallback).
> **Note:** The preferred way to register a reporting callback is directly on `WearablesStdApi` / `WearablesCoroutineApi`, not via the service. The service-level methods are deprecated and kept only for backward compatibility.
>
> `WearablesStdApi.registerReportingCallback` and `WearablesCoroutineApi.registerReportingCallback` may be called before `init` — the callback will be active from the moment it is registered, even before SDK initialization.
#### 4.9.1 Input
**`ReportingCallback`**
| Parameter | Type | Description |
|-------------------|-------------------|----------------------------------------------------|
| reportingCallback | ReportingCallback | Implementation of the ReportingCallback interface. |
#### 4.9.2 Output
Returns `Unit`.
Throws no exceptions.
#### 4.9.3 Sample
**`Standard Callback`**
```kotlin
fun registerReportingCallback(reportingCallback: ReportingCallback) {
WearablesStdApi.registerReportingCallback(reportingCallback = reportingCallback)} Kotlin Coroutines
fun registerReportingCallback(reportingCallback: ReportingCallback) {
WearablesCoroutineApi.registerReportingCallback(reportingCallback = reportingCallback)} Deprecated — via service
// Deprecated: use WearablesStdApi.registerReportingCallback / WearablesCoroutineApi.registerReportingCallback instead
fun registerReportingCallback(reportingCallback: ReportingCallback) {
WearablesStdApi .wearablesStdService .registerReportingCallback(reportingCallback = reportingCallback)} 4.10 unregisterReportingCallback
Synchronous. Offline.
Unregisters ReportingCallback.
Note: The preferred way to unregister a reporting callback is directly on the facade object (
WearablesStdApi/WearablesCoroutineApi), not via the service. The service-level methods are deprecated and kept only for backward compatibility.
4.10.1 Input
None
4.10.2 Output
Returns Unit.
Throws no exceptions.
4.10.3 Sample
Standard Callback
fun unregisterReportingCallback() {
WearablesStdApi.unregisterReportingCallback()} Kotlin Coroutines
fun unregisterReportingCallback() {
WearablesCoroutineApi.unregisterReportingCallback()} Deprecated — via service
// Deprecated: use WearablesStdApi.unregisterReportingCallback / WearablesCoroutineApi.unregisterReportingCallback instead
fun unregisterReportingCallback() {
WearablesStdApi .wearablesStdService .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
| Exception |
|---|
| RequestCancelledException |
| ProcessFailed |
| CommunicationFailed |
| WearableAppBusy |
| DeviceInactiveError |
| ReachedTimeout |
| AppNotRunning |
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`**
| Parameter | Type | Description |
|------------|--------|----------------------|
| wearableId | String | Wearable identifier. |
#### 4.12.2 Output
##### 4.12.2.1 Success
Returns an `IsAppInstalledOnWearableResult` object upon successful initiation.
**`IsAppInstalledOnWearableResult`**
| Parameter | Type | Description |
|-------------|---------|-----------------------------------------------------------------|
| isInstalled | Boolean | Flag determining whether companion app is installed on wearable |
##### 4.12.2.2 Failure
Failure callback with throwable.
**`Possible exceptions`**
| Exception |
|---------------------------|
| RequestCancelledException |
| ProcessFailed |
| WearableNotFound |
| WearableNotConnected |
#### 4.12.3 Sample
**`Standard Callback`**
```kotlin
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`**
| Parameter | Type | Description |
|---------------------|--------|--------------------------------|
| paymentInstrumentId | String | Payment instrument identifier. |
#### 5.1.2 Output
##### 5.1.2.1 Success
Returns an `GetWearablesIdsPairedWithTokenResult` object upon successful initiation.
**`GetWearablesIdsPairedWithTokenResult`**
| Parameter | Type | Description |
|--------------|----------------|--------------------------------|
| wearablesIds | List\<String\> | List of wearables identifiers. |
##### 5.1.2.2 Failure
Failure callback with throwable.
**`Possible exceptions`**
| Exception |
|----------------------------|
| RequestCancelledException |
| ProcessFailed |
| NetworkConnectionException |
#### 5.1.3 Sample
**`Standard Callback`**
```kotlin
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`**
| Parameter | Type | Description |
|---------------------|--------|--------------------------------|
| wearableId | String | Wearable identifier. |
| paymentInstrumentId | String | Payment instrument identifier. |
#### 5.2.2 Output
##### 5.2.2.1 Success
Returns an `IsWearablePairedWithTokenResult` object upon successful initiation.
**`IsWearablePairedWithTokenResult`**
| Parameter | Type | Description |
|-----------|---------|------------------------------------------------------------|
| isPaired | Boolean | Defines whether the wearable and payment token are paired. |
##### 5.2.2.2 Failure
Failure callback with throwable.
**`Possible exceptions`**
| Exception |
|----------------------------|
| RequestCancelledException |
| ProcessFailed |
| NetworkConnectionException |
#### 5.2.3 Sample
**`Standard Callback`**
```kotlin
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`**
| Parameter | Type | Description |
|---------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| paymentInstrumentId | String | Payment instrument identifier. |
| wearableId | String? | Flag determining whether tokenization (and resulting token) would be removed for particular wearable or all wearables for which payment instrument was tokenized. |
#### 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`**
| Exception |
|----------------------------|
| RequestCancelledException |
| ProcessFailed |
| CommunicationFailed |
| AppNotInstalled |
| WearableAppError |
| WearableAppBusy |
| DeviceInactiveError |
| ReachedTimeout |
| WearableNotFound |
| WearableNotConnected |
| AppNotRunning |
| NetworkConnectionException |
#### 5.3.3 Sample
**`Standard Callback`**
```kotlin
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`**
| Exception |
|----------------------------|
| RequestCancelledException |
| ProcessFailed |
| CommunicationFailed |
| AppNotInstalled |
| WearableAppError |
| WearableAppBusy |
| DeviceInactiveError |
| ReachedTimeout |
| WearableNotFound |
| WearableNotConnected |
| AppNotRunning |
| NetworkConnectionException |
#### 5.4.3 Sample
**`Standard Callback`**
```kotlin
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`**
| Parameter | Type | Description |
|------------|------------|----------------------|
| wearableId | String | Wearable identifier. |
| token | TokenModel | Payment token. |
**`TokenModel`**
| Parameter | Type | Description |
|---------------------------------|-------------|-------------------------------------------------------------------|
| paymentInstrumentId | String | Payment instrument identifier. |
| tokenType | TokenType | Value class encapsulating token type as a [value] String field. |
| tokenExpiry | String? | Token expiration date. |
| tokenLastFourDigits | String? | Token last 4 digits. |
| paymentInstrumentExpirationDate | String? | Payment instrument expiration date. |
| paymentInstrumentLastFourDigits | String | Payment instrument last 4 digits. |
| tokenStatus | TokenStatus | Value class encapsulating token status as a [value] String field. |
| description | String | Token description. |
| visualFile | File? | Payment instrument visual file. |
| visualIndex | Int | Index of payment instrument visual. |
**`TokenType`**
| Type | Description | Supporting const |
|-------------|------------------|-----------------------|
| VISA | Visa type. | TokenType.VISA |
| MASTER_CARD | MasterCard type. | TokenType.MASTER_CARD |
| EMPTY | Empty type. | TokenType.EMPTY |
**`TokenStatus`**
| Type | Description | Supporting const |
|-----------|------------------|-----------------------|
| ACTIVE | Active token. | TokenStatus.ACTIVE |
| SUSPENDED | Suspended token. | TokenStatus.SUSPENDED |
| DELETED | Deleted token. | TokenStatus.DELETED |
#### 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`**
| Exception |
|---------------------------|
| RequestCancelledException |
| ProcessFailed |
| CommunicationFailed |
| AppNotInstalled |
| WearableAppError |
| WearableAppBusy |
| DeviceInactiveError |
| ReachedTimeout |
| WearableNotFound |
| WearableNotConnected |
| AppNotRunning |
#### 5.5.3 Sample
**`Standard Callback`**
```kotlin
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`**
| Parameter | Type | Description |
|---------------------|--------|--------------------------------|
| wearableId | String | Wearable identifier. |
| paymentInstrumentId | String | Payment instrument identifier. |
#### 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`**
| Exception |
|----------------------------|
| RequestCancelledException |
| ProcessFailed |
| CommunicationFailed |
| AppNotInstalled |
| WearableAppError |
| WearableAppBusy |
| DeviceInactiveError |
| ReachedTimeout |
| WearableNotFound |
| WearableNotConnected |
| AppNotRunning |
| NetworkConnectionException |
#### 5.6.3 Sample
**`Standard Callback`**
```kotlin
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](#13-prerequisites) 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](#32-synchronization) which might require Internet connection
after all.
#### 5.7.1 Input
**`HandleTokenStatusChangeData`**
| Parameter | Type | Description |
|---------------------|-------------|-------------------------------------------------------------------|
| wearableId | String | Wearable identifier. |
| paymentInstrumentId | String | Payment instrument identifier. |
| tokenStatus | TokenStatus | Value class encapsulating token status as a [value] String field. |
**`TokenStatus`**
| Type | Description | Supporting const |
|-----------|------------------|-----------------------|
| ACTIVE | Active token. | TokenStatus.ACTIVE |
| SUSPENDED | Suspended token. | TokenStatus.SUSPENDED |
| DELETED | Deleted token. | TokenStatus.DELETED |
#### 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`**
| Exception |
|---------------------------|
| RequestCancelledException |
| ProcessFailed |
| CommunicationFailed |
| AppNotInstalled |
| WearableAppError |
| WearableAppBusy |
| DeviceInactiveError |
| ReachedTimeout |
| WearableNotFound |
| WearableNotConnected |
| AppNotRunning |
#### 5.7.3 Sample
**`Standard Callback`**
```kotlin
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 fromUcpPaymentInstrumentEventListener 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
| Parameter | Type | Description |
|---|---|---|
| wearableId | String | Wearable identifier. |
| paymentInstrumentId | String | Payment instrument identifier. |
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
| Exception |
|---|
| RequestCancelledException |
| ProcessFailed |
| CommunicationFailed |
| AppNotInstalled |
| WearableAppError |
| WearableAppBusy |
| DeviceInactiveError |
| ReachedTimeout |
| WearableNotFound |
| WearableNotConnected |
| AppNotRunning |
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.
| Parameter | Type | Description |
|---|---|---|
| logs | List<DumpLogsDetailsModel> | List of logs from wearable. |
DumpLogsDetailsModel
| Parameter | Type | Description |
|---|---|---|
| time | String | Error occurrence time. |
| message | String | Error message. |
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](#711-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](#712-report-categories) 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`**
| Parameter | Type | Description |
|-----------|-------------|-----------------------------------------------------------------------------------------------------|
| report | ReportModel | Data collected to report new event. It is a sealed class with two subclasses - `Event` and `Error`. |
**`ReportModel.Event`**
| Parameter | Type | Description |
|---------------------|---------|--------------------------------------------------------------------------------------------|
| name | String | Name of the event that occurred by which it could be easily searched. |
| description | String | Description of the event providing more detail. |
| timestamp | Long | Timestamp of the moment the event occurred. |
| paymentInstrumentId | String? | An identifier of payment instrument if any was involved in the event. |
| params | String | Additional parameters: e.g. version number of various SDKs involved for further reference. |
**`ReportModel.Error`**
| Parameter | Type | Description |
|---------------------|--------------------|--------------------------------------------------------------------------------------------|
| name | String | Name of the error that occurred by which it could be easily searched. |
| description | String | Description of the error providing more detail. |
| timestamp | Long | Timestamp of the moment the error occurred. |
| paymentInstrumentId | String? | An identifier of payment instrument if any was involved in the error. |
| params | String | Additional parameters: e.g. version number of various SDKs involved for further reference. |
| exception | WearablesException | Instance of an error that occurred. |
##### 7.1.1.2 Output
Returns an empty `OnNewReportResult` object.
##### 7.1.1.3 Sample
**`Standard Callback`**
```kotlin
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:
| Name | Description |
|---|---|
| SDK_WEAR_TOKEN_UPDATE_CREDENTIALS | Operations on transaction credentials, e.g. adding them to wearable, requesting replenish, synchronizing state with mobile app. |
| SDK_WEAR_TOKEN_UPDATE_STATUS | Operations on tokenized payment instrument, e.g. updating its state, deleting it altogether. |
| SDK_WEAR_ENCRYPTED_DATA | Operations on encrypted data, e.g. creating secure session, obtaining token or its credentials. |
| SDK_WEAR_SYNC_RESULT | Operations regarding synchronization process; as it is multi-step process those events might be very diverse. |
| SDK_WEAR_CONNECTION | Various events from elements engaged in connection monitoring process, e.g. hardware producer's software, foreground service, wearable app. |
| SDK_WEAR_API_REQUEST_{type} | Requests sent from this SDK to wearable app; each particular request will provide appropriate type suffix. |
| SDK_WEAR_API_RESPONSE_{type} | Responses obtained from wearable app by this SDK; each particular response will have a type suffix of request it is responding to. |
| SDK_WEAR_DEVICE_PAIRING | Operations regarding process of pairing wearable device with mobile app that enables future exchange of encrypted data. |
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
| Parameter | Type | Description |
|---|---|---|
| wearable | WearableModel | Wearable device that has been connected. |
| hasPairedTokens | Boolean | Flag determining whether this wearable has any tokens added for payment. |
WearableModel
| Parameter | Type | Description |
|---|---|---|
| id | String | Identifier of the wearable. |
| name | String | Name of the wearable. |
| softwareVersion | String | Software version of the wearable. |
| isConnected | Boolean | Defines whether the wearable is connected. |
| pairedTokensIds | List<String> | List of ids of paired tokens. |
| deviceModel | String | Model of the device provided by the producer. |
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
| Parameter | Type | Description |
|---|---|---|
| wearable | WearableModel | Wearable device that has been disconnected. |
WearableModel
| Parameter | Type | Description |
|---|---|---|
| id | String | Identifier of the wearable. |
| name | String | Name of the wearable. |
| softwareVersion | String | Software version of the wearable. |
| isConnected | Boolean | Defines whether the wearable is connected. |
| pairedTokensIds | List<String> | List of ids of paired tokens. |
| deviceModel | String | Model of the device provided by the producer. |
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
| Parameter | Type | Description |
|---|---|---|
| wearable | WearableModel | Wearable device that is missing the app. |
WearableModel
| Parameter | Type | Description |
|---|---|---|
| id | String | Identifier of the wearable. |
| name | String | Name of the wearable. |
| softwareVersion | String | Software version of the wearable. |
| isConnected | Boolean | Defines whether the wearable is connected. |
| pairedTokensIds | List<String> | List of ids of paired tokens. |
| deviceModel | String | Model of the device provided by the producer. |
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
| Parameter | Type | Description |
|---|---|---|
| wearableId | String | Wearable identifier. |
7.3.1.2 Output
7.3.1.2.1 Success
Returns a CreateSecureSessionResult object upon successful initiation.
| Parameter | Type | Description |
|---|---|---|
| secureSessionData | String | Data required for establishing secure session with wearable. |
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
| Parameter | Type | Description |
|---|---|---|
| wearableId | String | Wearable identifier. |
| paymentInstrumentId | String | Payment instrument identifier. |
| secureSessionData | String | Data required for encryption of token data to transfer it to wearable in a secure way. |
7.3.2.2 Output
7.3.2.2.1 Success
Returns a GetEncryptedTokenResult object upon successful initiation.
| Parameter | Type | Description |
|---|---|---|
| encryptedToken | String | Encrypted token data to be transferred to wearable. |
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
| Parameter | Type | Description |
|---|---|---|
| wearableId | String | Wearable identifier. |
| paymentInstrumentId | String | Payment instrument identifier. |
| secureSessionData | String | Data required for encryption of token data to transfer it to wearable in a secure way. |
7.3.3.2 Output
7.3.3.2.1 Success
Returns a GetEncryptedTokenTransactionCredentialsResult object upon successful initiation.
| Parameter | Type | Description |
|---|---|---|
| encryptedTokenTransactionCredentials | String | Encrypted token transaction credentials to be transferred to wearable. |
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
| Parameter | Type | Description |
|---|---|---|
| wearableId | String | Wearable identifier. |
| usedCredentialsInfo | String | Encoded information about current state of token credentials on wearable. |
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
| Parameter | Type | Description |
|---|---|---|
| wearableId | String? | Identifier of wearable for which current state of tokenized payment instruments should be obtained. If not provided, information would be retrieved for all wearables currently having tokenized payment instruments. |
7.3.5.2 Output
7.3.5.2.1 Success
Returns a GetTokenizedPaymentInstrumentsResult object upon successful initiation.
| Parameter | Type | Description |
|---|---|---|
| paymentInstruments | List<TokenizedPaymentInstrumentModel> | List of payment instruments that have been tokenized. Might consist of elements applicable for all wearables or particular wearable only (depending on value of wearableId parameter). |
TokenizedPaymentInstrumentModel
| Parameter | Type | Description |
|---|---|---|
| paymentInstrumentId | String | Payment instrument identifier. |
| paymentTokenId | String | Token identifier. |
| status | TokenStatus | Value class encapsulating token status as a [value] String field. |
| credentialsCount | Int | Amount of token credentials left to be used for contactless transaction. |
| paymentDeviceId | String? | Wearable identifier for which this payment instrument was tokenized. |
TokenStatus
| Type | Description | Supporting const |
|---|---|---|
| ACTIVE | Active token. | TokenStatus.ACTIVE |
| SUSPENDED | Suspended token. | TokenStatus.SUSPENDED |
| DELETED | Deleted token. | TokenStatus.DELETED |
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
| Parameter | Type | Description |
|---|---|---|
| wearableId | String | Wearable identifier. |
| paymentInstrumentId | String | Payment instrument identifier. |
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
| Parameter | Type | Description |
|---|---|---|
| wearableId | String | Wearable identifier. |
| paymentInstrumentId | String | Payment instrument identifier. |
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
| Parameter | Type | Description |
|---|---|---|
| wearableId | String | Wearable identifier. |
| pairDeviceData | String | Data required for pair wearable with mobile app. It enables further creation of secure session and transferring encrypted data. |
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
| Parameter | Type | Description |
|---|---|---|
| wearableId | String | Wearable identifier. |
7.3.9.2 Output
7.3.9.2.1 Success
Returns an IsDevicePairedResult object upon successful initiation.
| Parameter | Type | Description |
|---|---|---|
| isDevicePaired | Boolean | Information whether wearable is already paired with mobile app. |
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.
| Parameter | Type | Description |
|---|---|---|
| canPerformSync | Boolean | Flag determining whether synchronization process might be initiated. |
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.
| Parameter | Type | Description |
|---|---|---|
| canAutomaticallyStartConnectionService | Boolean | Flag determining whether ConnectionService can be automatically started |
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`**
| Parameter | Type | Description |
|---------------------|--------|--------------------------------|
| wearableId | String | Wearable identifier. |
| paymentInstrumentId | String | Payment instrument identifier. |
#### 7.5.1.2 Output
Returns an empty `OnCredentialsAddedResult` object.
#### 7.5.1.3 Sample
**`Standard Callback`**
```kotlin
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
startConnectionServicemethod - 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 ofConnectionServicewhenever
mobile app enters foreground.
8.11. Version 2.1.1
- Fixed internal build issue.
8.12. Version 2.1.2
- Added
deviceModelfield toWearableModel.
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.
8.18. Version 2.1.8
- Added
WearablesException.SdkNotInitialized(with non-nullorigin) thrown when a service is
used beforeinit;ConnectionServicestarted beforeinitstops itself immediately. - Added
WearablesException.MissingDefinitionreturned when an internal definition cannot be
resolved (typically a side effect of missinginit); carries the original error ascause. - Added internal 5-minute timeout safeguard around the synchronization flow.
- Added
registerReportingCallbackandunregisterReportingCallbackdirectly onWearablesStdApi
andWearablesCoroutineApifacades. This is now the preferred way to register a reporting
callback, independent of SDK initialization order. - Deprecated
registerReportingCallbackandunregisterReportingCallbackonWearablesStdService
andWearablesCoroutineService— use the facade-level methods instead.
8.19. Version 2.1.9
- Internal. Prevent PIN screen loop on Wearable's new software.
8.20. Version 2.1.10
- Internal changes improving SDK.