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

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 is built, SCA Wallet access is requested by calling the WalletManager#connect() method.

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

Callback	Description
WalletManagerCallback#onConnectionSuccess()	The wallet is ready and any of its services can be used.
WalletManagerCallback#onProvisioningRequired()	The wallet access is refused because there is no initialized wallet in the app. The hosting app must first initialize a wallet and then attempt to access it again.
WalletManagerCallback#onCredentialsRequired()	The wallet access is refused because credentials must be provided. It can be either: New credentials to define when the wallet is accessed for the first time after provisioning. Current credentials when the wallet is accessed after log out. The hosting App must request and acquire credentials from the customer, then forward them to the SDK as method arguments through a new call to WalletManager#connect(currentCredentials,newCredentials). If the Wallet is configured to not enforce access protection, this callback is never called.
WalletManagerCallback#onConnectionError()	The 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 explicitly blacklisted. Checking device eligibility is done by calling the WalletProvisioning#checkEligibility() method.

This starts a light operation and executes the following callbacks.

Callback	Description
WalletProvisioningCallback#onDeviceEligible()	If the device is considered eligible for SCA services. Features available on the SCA wallet are provided as method argument. After this callback, the hosting app can proceed with wallet provisioning.
WalletProvisioningCallback#onDeviceNotEligible()	If the device is considered not eligible for SCA services (wallet provisioning isn't possible). The eligibility denial reason is provided as method argument with the eligibility denial reference (i.e., the identifier used to record this specific eligibility denial on the back end).
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 instantiated with the following parameters.

Parameter	Description
patternName	The name of the authentication pattern to use for this authentication. Can be: patterns.NONE.name for none authentication patterns.PIN.name for PIN authentication patterns.BIOMETRY.name for Biometric authentication
message	The 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. You must use the CustomerAuthenticatedSignatureType.LocalJws option.
signatureInputData	Custom, context-related information that is part of the signed data.

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

When the CustomerAuthenticatedSignature is successfully completed, you're notified by the CustomCustomerAuthenticatedProcessCallback#onProcessSuccess() callback. The generated signature result can be fetched by calling CustomerAuthenticatedSignature#getResult().

SCA Proof flow

The following diagram illustrates the generation of SCA Proofs using type PIN. It assumes the provisioning is 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

SCA Wallets may have the following states.

State	Description
Not provisioned	The app has not initialized the SDK yet, so no SCA wallet exists on it.
Ready	The SDK was initialized by the app, an SCA wallet was provisioned into it, and its properties and features can be accessed by the app (after establishing a connection to the SCA wallet).
Locked	The SCA wallet provisioned into the app is locked. Its properties and features aren't accessible to the app until the SCA wallet is unlocked from the back end.
Logout	Access to properties and features of the SCA wallet provisioned into the app requires first a customer authentication.

Authentication

Methods

The user is prompted to authenticate differently depending on the method:

• Pin – Using a 6 to 8 digits PIN code.
• Biometric – Using the local biometric authentication system of the device.
• None – No input required, the operation is transparent.

You may use indistinctly Pin or Biometric, depending on the capabilities of the device.

Regardless of the method, basic checks are carried out to ensure the mobile device is legitimate and 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": {}
}

With parameters to be signed

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

Payload examples

Find below a series of examples that illustrate different payloads.

GET /v1/cardimages

Request example:

CURL

GET {baseURL}/v1/cardimages?cardId=123456&encryptionMethod=2

Signed data:

JSON

{
  "url": "{baseURL}/v1/cardimages",
  "body": {
    "cardId":"123456"
  }
}

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

Request example:

CURL

PUT {baseURL}​/v1/cards​/{id}​/Activate​?accessTag=12345

Signed data:

JSON

{
  "url": "{baseURL}/v1/cards​/{id}​/Activate",
  "body": {}
}

POST /v1/beneficiaries

Request example:

CURL

POST {baseURL}/v1/beneficiaries?accessTag=12345
{
    "userId": "12345",
    "name": "Alex Oak"
    "address": "15 Magnolia road",
    "iban": "FR113000300030592123456789",
    "bic": "SOGEFRPPXXX",
    "usableForSct": true
}

Signed data:

JSON

{
  "url": "{baseURL}/v1/beneficiaries",
  "body": {
    "userId": "12345",
    "name": "Alex Oak",
    "address": "15 Magnolia road",
    "iban": "FR113000300030592123456789",
    "bic": "SOGEFRPPXXX",
    "usableForSct": true
  }
}

PUT /v1/users/

Request example:

CURL

PUT {baseURL}/v1/users/{userId}?accessTag=12345
{
	"phone": “0702030405”,
	"middleNames": "Chris"
}

Signed data:

JSON

{
	"url": "{baseURL}/v1/users/{userId}",
	"body": {
		"phone": “0765432190”
	}
}

PUT /v1/cards/{cardId}/Limits

Request example:

CURL

PUT {baseURL}/v1/cards/{cardId}/Limits
{
	"limitPaymentDay":25,
	"limitAtmDay":100
}

Signed data:

JSON

{
	"url": "{baseURL}/v1/cards/{cardId}/Limits",
	"body": {
		"limitPaymentDay":25,
		"limitAtmDay": 100
	}
}

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()

Compatibility chart

Langage	SDK Availability	iOS	Android
React Native
Java
Swift
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 available

Contact Treezor to request access to the SDK full documentation.

Download SDK

Sandbox

Production