# Mobile SDK

Information – SDK Wallet or SCA Wallet do not refer to Treezor Wallets

The SDK uses the terms Wallet or SCA Wallet to describe a secure enclave present locally on a mobile device where the private key is stored. Not to be mixed up with Treezor Wallets feature.

All the SDK features are provided through an SCA wallet object implemented in the SDK itself. It can be seen as a base layer, gathering configuration and security settings on which Strong Customer Authentication relies.

SCA Wallets are synchronized between the mobile device and Treezor back end.

The main property of the SCA wallet is its state, evolving from actions triggered on the back end or on hosting app side, and defining how an SCA wallet is accessible to the hosting app.

Requirements for mobile compatibility on your end users side

Android

Minimum supported version – Android 5.0 Lollipop (API level 21)
Target version – Tested with Android versions until Android 13 (API level 33)

iOS

Minimum supported version – iOS 11
Minimum supported version for pushing a Card to Apple Pay – iOS 13.4
Swift 5

# Access

In order to request SCA proofs, the hosting app must first build a WalletManager object with a custom implementation of WalletManagerCallback. The callback functions will be called by the SDK upon the completion of asynchronous actions requested on the WalletManager instance.

Once a WalletManager object has been built, SCA wallet access is requested by calling the WalletManager#connect() method.

connect() calls are asynchronous and upon completion trigger one of the following method of the WalletManager:

WalletManagerCallback#onConnectionSuccess() wallet is ready and any of its services can be used
WalletManagerCallback#onProvisioningRequired() wallet access is refused because there is no wallet currently initialized in the app. The hosting app must first initilize a wallet and then attempt to access it again.
WalletManagerCallback#onCredentialsRequired() wallet access is refused because credentials must be provided to access to it. It can be either new credentials to define when wallet is accessed for the first time after provisioning or current credentials to provide when wallet is accessed after having been logged out. Hosting App must request customer to provide credentials, and after they have been acquired, forward them to the SDK through a new call to WalletManager#connect(currentCredentials,newCredentials) in which they are passed as method arguments. In case Wallet is configured not to enforce any access protection, this callback is never called.
WalletManagerCallback#onConnectionError() wallet access cannot be established, for a specific reason provided as method argument.

Calls to the connect() method happen mostly locally, but can require online connectivity in some specific cases (for example when credentials are provided or when critical security checks must be carried out).

Best practice – Ensure that the SCA Wallet handled by the app is up to date

Don't handle the SCA Wallet instance returned by the SDK statically or in a singleton on the hosting app side. Each time a new context on the App needs to interact with an SCA Wallet, it must connect to a WalletManager and wait for onConnectionSuccess callback function.

# Device Eligibility

SCA features can be forbidden if the device is rooted or if the device model is explicitely blacklisted. Checking device eligility is done by calling the WalletProvisioning#checkEligibility() method.

This starts a light operation and executes the following callbacks:

WalletProvisioningCallback#onDeviceEligible() if the device has been considered as eligible to SCA services. The list of features available on the SCA wallet is provided as method argument. Following this callback, hosting app can proceed to wallet provisioning.
WalletProvisioningCallback#onDeviceNotEligible() if the device has been considered as not eligible to SCA Services, thus wallet provisioning is not possible on it. The eligibility denial reason is provided as method argument as well as an eligibility denial reference corresponding to the identifier under which this specific eligibility denial has been recorded on back end side.
WalletProvisioningCallback#onCheckEligibilityError() if the eligibility check has failed, for a specific reason provided as method argument.

# Provisioning flow

The following diagram illustrates the provisioning procedure. This applies to one User and one mobile device.

Best practice – Your code must be event-based

Although this diagram is fairly procedural for clarity, your code must be event-based to handle all possibilities.

# Signature

SCA proof capabilities are provided by the SDK via CustomerAuthenticatedSignature, it produces a signature once the user has performed the required authentication. This signature is generated locally within Entrust SDK and is returned to the hosting app.

CustomerAuthenticatedSignature must first be instanciated with the following parameters:

patternName Name of the authentication pattern to use for this authentication.
- patterns.NONE.name for none authentication
- patterns.PIN.name for PIN authentication
- patterns.BIOMETRY.name for Biometric authentication
message Message to display to the customer. Must be set if the SDK is used to display the UI. In any case, this information is part of the signed data
signatureType Type of signature result to generate.
- CustomerAuthenticatedSignatureType.LocalJws is the only option to use
signatureInputData Custom, context-related information that is part of the signed data.

Once instanciated, you must call CustomerAuthenticatedSignature#sign() to start the signature process.

Upon CustomerAuthenticatedSignature successful completion, notified by CustomCustomerAuthenticatedProcessCallback#onProcessSuccess() callback, the generated signature result can be fetched by calling the CustomerAuthenticatedSignature#getResult().

# SCA Proof flow

The following diagram illustrates the generation of SCA Proofs using type PIN. It assumes that provisioning has been completed.

Best practice – Your code must be event-based

Although this diagram is fairly procedural for clarity, your code must be event-based to handle all possibilities.

# SCA Wallet states

Not provisioned: The app has not initialized the SDK yet and thus no SCA wallet exists on it.
Ready: The SDK has been initialized by the app, an SCA wallet has been provisioned into it and its properties and features can be accessed by the app (after establishing a connexion to the SCA wallet).
Locked: The SCA wallet provisioned into the app has been locked. Its properties and features are not accessible to the app until the SCA wallet is unlocked from back end side.
Logout: Access to properties and features of the SCA wallet provisioned into the app requires first a customer authentication.

# Integration

# Authentication

# Methods

Pin: The Customer is authenticated using a 6 to 8 digits PIN code.
Biometric: The Customer is prompted to authenticate through the local biometric authentication system of the device.
None: The Customer is not prompted for any input, the operation is transparent.

You may use indistinctly Pin or Biometric, depending on the Device's capabilities.

In addition, all methods do basic checks to ensure the mobile device is legitimate and that it has not been altered or cloned.

# Events

The following functions can be called by the SDK upon SCA Wallet updates.

Event	Description
`WalletEventListener#onWalletSettingUpdated()`	The SCA wallet settings are updated.
`WalletEventListener#onWalletProductsUpdated()`	The SCA wallet products are updated.
`WalletEventListener#onWalletCountersUpdated()`	The SCA wallet passcode (PIN Code) attempt counter is updated.
`WalletEventListener#onCustomerCredentialsReset()`	The SCA wallet passcode (PIN Code) has been reset.
`WalletEventListener#onWalletLocked()`	The SCA wallet has been locked.
`WalletEventListener#onWalletUnlocked()`	The SCA wallet has been unlocked.
`WalletEventListener#onDeviceEligibilityLost()`	The current device is no longer eligible to SCA service.
`WalletEventListener#onWalletDeleted()`	The SCA wallet has been deleted.
`WalletEventListener#onWalletLoaded()`	The SCA wallet has completed its initialization.
`WalletEventListener#onAppSunsetScheduled()`	The current version of the mobile application has been deprecated.

# Payload

When providing a payload to the SDK for signature, it should be in the following format, with:

The url (string) – Always populated with the endpoint that requires the SCA
The body (object) – Populated with parameters to sign, and left as an empty array when no parameters have to be signed.

# No parameters to be signed

{
  "url": "string",
  "body": {}
}

1
2
3
4

# With parameters to be be signed

{
  "url": "string", 
  "body": {
    "foo0": "bar0",
	"foo1": "bar1"
  }
}

1
2
3
4
5
6
7

# Payload examples

Find below a series of examples that illustrate different payloads.

# GET /v1/cardimages

Request example:

Signed data:

# PUT /v1/cards/{id}/Activate

Request example:

Signed data:

# POST /v1/beneficiaries

Request example:

Signed data:

# PUT /v1/users/{userId}

Request example:

Signed data:

# PUT /v1/cards/{cardId}/Limits

Request example:

Signed data:

# PIN Change

To change the PIN of an SCA Wallet, you have to follow these steps.

# Check the current PIN

Call the WalletManager#checkCredentials(currentCredentials) method. As the operation is async:

Subscribe to the WalletManager#onAsyncRequestSuccess callback for the success response
Subscribe to the WalletManager#onAsyncRequestError callback for the error response

# Change the PIN

Use the WalletManager#changeCredentials(currentCredentials,newCredentials) method. As the operation is async:

Subscribe to the WalletManager#onAsyncRequestSuccess callback for the success response
Subscribe to the WalletManager#onAsyncRequestError callback for the error response

# Disconnection

When disconnecting from an SCA Wallet, you have to follow these steps:

WalletManager#disconnect()
WalletManager#clean()

1
2

# Compatibility chart

Langage	iOS	Android
React Native (opens new window)
Java (opens new window)
Swift (opens new window)
Cordova
Flutter
Dart
Kotlin
Objective C
Web	N/A	N/A

Information – The SDK is not compatible with pure Web applications

If your mobile stack is not available yet, get in touch with your Implementation Manager.

Reading – Full SDK Documentation availabe

Contact Treezor to request access to the SDK full documentation.

# Download SDK

← Mobile Flutter Bridge Web-Hybrid →

# Mobile SDK

# Access

# Device Eligibility

# Provisioning flow

# Signature

# SCA Proof flow

# SCA Wallet states

# Integration

# Authentication

# Methods

# Events

# Payload

# No parameters to be signed

# With parameters to be be signed

# Payload examples

# GET /v1/cardimages

# PUT /v1/cards​/{id}​/Activate

# POST /v1/beneficiaries

# PUT /v1/users/{userId}

# PUT /v1/cards/{cardId}/Limits

# PIN Change

# Check the current PIN

# Change the PIN

# Disconnection

# Compatibility chart

# Download SDK

# PUT /v1/cards/{id}/Activate