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:
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:
|
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
json
{
"url": "string",
"body": {}
}
With parameters to be signed
json
{
"url": "string",
"body": {
"foo0": "bar0",
"foo1": "bar1"
}
}
Payload examples
Find below a series of examples that illustrate different payloads.
GET /v1/cardimages
Request example:
bash
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:
bash
PUT {baseURL}/v1/cards/{id}/Activate?accessTag=12345
Signed data:
json
{
"url": "{baseURL}/v1/cards/{id}/Activate",
"body": {}
}
POST /v1/beneficiaries
Request example:
bash
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:
bash
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:
bash
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:
c
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.