SCA Wallets
An SCA Wallet is the secure enclave locally present on a device. This digital safe contains a private key necessary for Strong Customer Authentication.
By default, the number of active SCA Wallets is limited per device type as follows:
Device | Limits |
---|---|
Mobile | 1 active SCA Wallet per device. |
Web browser | 5 active SCA Wallets per device. |
If these limits are exceeded, an HTTP error is returned.
Caution – The SDK uses the term Wallet differently from Treezor
In the SDK, the term Wallet or SCA Wallet describes the secure enclave on a mobile device, not Treezor Wallets.
Automatic Creation
An SCA Wallet can be automatically created when creating a new User:
- Without any additional information when using the SDK. This requires a specific configuration.
- By adding the necessary credentials and passcode when using WebAuthn
Using the SDK
When using the SDK, an SCA Wallet is automatically created when the User is created in the Treezor API and:
- A keypair is generated for this SCA Wallet.
- The SCA Wallet is associated to the new User.
- Treezor sends you a
sca.wallet.create
webhook notifying you of the SCA Wallet creation.
Using WebAuthn
If you're using the Web Native solution to sign the operation, optional fields must be provided in when creating a User for the SCA Wallet creation to occur.
Attribute | Type | Description |
---|---|---|
webauthn | string | The PublicKeyCredential after the WebAuthn Register, encoded in base64. |
passcode | string | Required if the webauthn field is provided. Must be base64 encoded and encrypted. |
See the Web Native article, Device enrollment section for more information.
Manual Creation
Note – For Users created after SCA activation only
If your Users were created in the Treezor API before the SCA feature was enabled, you will have to create their SCA Wallets manually yourself, in an automated way.
Parameters
Below are the parameters to create an SCA Wallet manually.
Attribute | Type | Description |
---|---|---|
userId | string | The unique identifier of the user the SCA Wallet is to be attached to. |
scaWalletTag | string | Custom value for the SCA Wallet. Can be used to name the device for which the new SCA Wallet is created. Max length: 256 characters. |
authMethod | array | The chosen method for the 2-factor authentication when signing the operation with the Web Native solution. Must be two of the following (strings): OTP SMS , OTP EMAIL , ID , OTHER . |
sca | string | For the Web Native solution, when creating the SCA Wallet as an end user (required if no authMethod is provided). |
webauthn | string | For the Web Native solution. The PublicKeyCredential after the WebAuthn Register, encoded in base64. |
passcode | string | Required if the webauthn field is provided and if there is no existing passcode for the user yet. Must be base64-encoded and encrypted. |
Request when using the SDK
To manually create an SCA Wallet, you can use the following request.
bash
curl -X POST {baseUrl}/core-connect/sca/scawallets/ \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'
Here is an example of {payload}
:
json
{
"userId":"123456",
"scaWalletTag":"Iphone 13 mini" // Can be the device name (the SCA Wallet is created for)
}
Answers with a 200
HTTP Status Code and the following response.
json
{
"id": "3532d3d44dd999e8957e07cc7e860b2a",
"status": "CREATED",
"subStatus": "CREATED_READY",
"passcodeStatus": "NOT_SET",
"locked": false,
"lockReasons": [],
"lockMessage": null,
"settingsProfile": "default",
"activationCode": "**********************",
"creationDate": "2023-07-12T17:15:25+02:00",
"deletionDate": null,
"activationCodeExpiryDate": "2023-07-12T17:35:25+02:00",
"authenticationMethods": [
{
"type": "DEVICE_BIOMETRIC",
"usages": [
"STRONG_CUSTOMER_AUTHENTICATION"
],
"parameters": {
"validityDuration": 60
}
},
{
"type": "HYBRID_PIN",
"usages": [
"WALLET_MANAGEMENT",
"STRONG_CUSTOMER_AUTHENTICATION"
],
"parameters": {
"maxAttempts": 3,
"validityDuration": 60
}
},
{
"type": "NONE",
"usages": [
"STRONG_CUSTOMER_AUTHENTICATION"
],
"parameters": []
},
{
"type": "CLOUD_PIN",
"usages": [
"WALLET_MANAGEMENT",
"STRONG_CUSTOMER_AUTHENTICATION"
],
"parameters": {
"maxAttempts": 3,
"validityDuration": 60
}
}
],
"invalidActivationAttempts": null,
"userId": "3400118",
"scaWalletTag": "Iphone 13 mini"
}
Treezor also sends you a sca.wallet.create
webhook. Note that the activationCode
attribute is only populated in the response, it cannot be retrieved later.
Request when using the WebNative solution
To manually create an SCA Wallet, you can use the following request.
bash
curl -X POST {baseUrl}/core-connect/sca/scawallets/ \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'
Here is an example of {payload}
:
json
{
"userId": "3400118",
"scaWalletTag":"Iphone 12 mini",
"passcode": "2kdq6KPRzfnGoV8[...]zzwAv1OYbS0w==", // Truncated for readability
"webauthn":"eyJyZSI6ey[...]xem9mUSIaWMta2V5In0=", // Truncated for readability
"authMethod": ["OTP SMS", "ID"]
}
Answers with a 200
HTTP Status Code and the following response.
json
{
"id": "3532d3d44dd999e8957e07cc7e860b2a",
"status": "CREATED",
"subStatus": "CREATED_READY",
"passcodeStatus": "NOT_SET",
"locked": false,
"lockReasons": [],
"lockMessage": null,
"settingsProfile": "default",
"mobileWallet": null,
"activationCode": "**********************",
"creationDate": "2023-07-12T17:15:25+02:00",
"activationDate":null,
"deletionDate": null,
"activationCodeExpiryDate": "2023-07-12T17:35:25+02:00",
"authenticationMethods": [
{
"userHandle": "dGVzdEB3ZWJhdXRobg",
"publicKeyCredentialId": "-7TzaTMjA3dk-1fLf3fEch_Rwqp3hxB0-yaxQXoqEeo",
"aaguid": "adce0002-35bc-c60a-648b-0b25f1f05503",
"uvInitialized": true,
"attestationType": "self",
"backupEligible": false,
"counter": 0,
"otherUI": null,
"type": "public-key",
"transports": [],
"backupStatus": false,
"credentialPublicKey": "pQECAyYgA[...]qWcprI5yqvTz5P7-frvEHIzI", // Truncated for readability
"trustPath": {
"type": "Webauthn\\TrustPath\\EmptyTrustPath"
}
}
],
"invalidActivationAttempts": null,
"userId": "3400118",
"scaWalletTag": "Iphone 12 mini"
}
In this case, no webhook is sent upon creating the SCA Wallet.
Provisioning
You must provision the SCA Wallet when using the SDK on the end user's device before the activationCodeExpiryDate
using either:
- The
WalletProvisioning#launch(activationCode)
SDK method - The
connect(activationCode)
method from the abstraction layer
Note – SCA Wallets must be provisioned before the expiration date
The activationCodeExpiryDate
is available in the sca.wallet.create
webhook. If the provisioning fails due to an expired activationCode
, you must delete the SCA Wallet and create a new one.
The activationCode
is provided in the sca.wallet.create
webhook. You may push silently the code to the end user's device to enable a seamless provisioning.
Once a given SCA Wallet has been provisioned into one app installation, it cannot be provisioned anymore and the activationCode
is consumed.
Locking
When you suspect that an SCA Wallet or device may have been compromised, you should lock the SCA Wallet and provide a reason for doing so.
bash
curl -X PUT {baseUrl}/core-connect/sca/scawallets/{scaWalletId}/lock \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'
Here is an example of {payload}
:
json
{
"lockReason":"LOST_DEVICE", // see list below
"lockMessage":"string" // optional, max 256 characters
}
You should get a 200
HTTP Status Code and the updated SCA Wallet object.
This will trigger the WalletEventListener#onWalletLocked()
event on the SDK.
Unlocking
If an SCA Wallet has been locked by one of your Support Users and after the legitimacy of the device has been reestablished, you may unlock it using the following request.
bash
curl -X PUT {baseUrl}/core-connect/sca/scawallets/{scaWalletId}/unlock \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json'
Answers with a 200
HTTP Status Code and the updated SCA Wallet object.
Unlocking the SCA Wallet also triggers the WalletEventListener#onWalletUnlocked()
event on the SDK.
Reset PIN
SCA Wallets are protected by PIN codes on end user devices.
To reset a PIN code, you can use the following request.
bash
curl -X PUT {baseUrl}/core-connect/sca/scawallets/{scaWalletId}/resetPin \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json'
Answers with a 200
HTTP Status Code and the updated SCA Wallet object.
The end user is now able to define a new PIN from their device.
Resetting the PIN code triggers the `WalletEventListener#onCustomerCredentialsReset() event on the SDK.
Retrieval
To retrieve an SCA Wallet you can use the following request.
bash
curl -X GET {baseUrl}/core-connect/sca/scawallets/{scaWalletId} \
--header 'Authorization: Bearer {accessToken}'
Answers with a 200
HTTP Status Code and returns the SCA Wallets object.
json
{
"id": "1a73b1eca9a64cf19a448b61dd494d15",
"status": "CREATED",
"subStatus": "CREATED_READY",
"passcodeStatus": "NOT_SET",
"locked": false,
"lockReasons": [],
"lockMessage": null,
"settingsProfile": "default",
"creationDate": "2023-07-13T15:29:05+02:00",
"deletionDate": null,
"activationCodeExpiryDate": "2023-07-13T15:49:05+02:00",
"authenticationMethods": [], // content of the array redacted for clarity
"invalidActivationAttempts": null,
"userId": "3400118",
"scaWalletTag": "Iphone 13 mini"
}
You may also retrieve all SCA Wallets belonging to a User using the following request.
bash
curl -X GET {baseUrl}/core-connect/sca/scawallets?userId={userId} \
--header 'Authorization: Bearer {accessToken}'
Answers with a 200
HTTP Status Code and returns the list of SCA Wallet objects.
json
{
"scawallets": [
{
"id": "1a73b1eca9a64cf19a448b61dd494d15",
"status": "CREATED",
"subStatus": "CREATED_READY",
"passcodeStatus": "NOT_SET",
"locked": false,
"lockReasons": [],
"lockMessage": null,
"settingsProfile": "default",
"creationDate": "2023-07-13T15:29:05+02:00",
"deletionDate": null,
"activationCodeExpiryDate": "2023-07-13T15:49:05+02:00",
"authenticationMethods": [], // content of the array redacted for clarity
"invalidActivationAttempts": null,
"userId": "3400118",
"scaWalletTag": "Iphone 13 mini"
}
]
}
Swap SCA Wallet Beta
Treezor offers a way for end users to enroll a new device to use for strong customer authentications while automatically deleting the previously enrolled device. It makes for a smoother experience than deleting the SCA Wallet first then creating a new one (since your users have a limited number of SCA Wallets).
This is considered a sensitive action, so users must be strongly authenticated before swapping devices. There are two use cases depending on whether the user:
- Owns the previous device – Then the user swaps with the SCA Proof from the previous device.
- No longer owns the previous device – Then you secure the swap with 2-factor authentication (e.g., OTP, ID check).
Upon using the swapping devices:
- The previous SCA Wallet is deleted (i.e., its status is set to
DELETED
). - A new SCA Wallet is created, and will be activated and/or usable on the new device.
- Treezor sends a
sca.wallet.swap
webhook.
Parameters
Below the key parameters for the swap endpoint. The necessary parameters may differ depending on the use case.
Attribute | Type | Description |
---|---|---|
removeScaWalletId | string | The unique identifier of the SCA Wallet that is to be deleted. |
swapReason | string | The reason for swapping SCA Wallet. Can be: LOST , STOLEN , or OTHER . |
authMethod | array | The chosen methods for the 2-factor authentication. Required if no sca is provided. Must be two of the following (strings): OTP SMS , OTP EMAIL , ID , OTHER . |
sca | string | The valid proof that authenticated the swap. Required if no authMethod is provided. |
scaWalletTag | string | Custom value for the SCA Wallet. Can be used to name the device for which the new SCA Wallet is created. Max length: 256 characters. |
Swap with SCA proof
In this case, the user still owns the previous device and can provide an SCA proof with it;
bash
curl -X POST {baseUrl}/core-connect/sca/scawallets/swap \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'
Here is an example of {payload}
(with SCA proof):
json
{
"removeScaWalletId":"5710a5536cf04712b922f04exx9da5e2",
"swapReason": "OTHER",
"sca":"{scaProof}",
"scaWalletTag":"Pixel 6"
}
Returns the newly created SCA Wallet object when successful. Treezor also sends a sca.wallet.swap
webhook.
Swap with 2-factor authentication
bash
curl -X POST {baseUrl}/core-connect/sca/scawallets/swap \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'
Here is an example of {payload}
(without SCA proof):
json
{
"swapReason":"LOST",
"removeScaWalletId":"5710a5536cf04712b922f04exx9da5e2",
"authMethod":["OTP SMS", "ID"],
"scaWalletTag":"iPhone 13"
}
Returns the SCA Wallet object when successful. Treezor also sends a sca.wallet.swap
webhook.
Deletion
A user using a single device should have a single SCA Wallet. The SCA Wallets of your users should be monitored as to avoid multiple or inactive SCA Wallets for a unique end user.
SCA Wallets should be deleted when:
- They haven't been used in a long time and probably can't be trusted anymore,
- The user declared their device stolen/lost,
- The user gets a new device that replaces the old one,
- Your commercial relationship with the user ends.
Alert – Automatic deletion
Treezor automatically deletes SCA Wallets that have been inactive for 6 months. An SCA Wallet is considered inactive if the last SCA Proof is older than 6 months.
You can use the following request to manually delete an SCA Wallet.
bash
curl -X DELETE {baseUrl}/core-connect/sca/scawallets/{scaWalletId} \
--header 'Authorization: Bearer {accessToken}' \
Answers with a 200
HTTP Status Code and the updated SCA Wallet object.
Deleting an SCA Wallet triggers the WalletEventListener#onWalletDeleted()
event on the SDK.
Structure of an SCA Wallet
Please note that this is an example of SCA Wallet object, and that some attributes such as the activationCode
are only valorized when relevant.
json
{
"id": "1a73b1eca9a64cf19a448b61dd494d15",
"status": "CREATED",
"subStatus": "CREATED_READY",
"passcodeStatus": "NOT_SET",
"locked": false,
"lockReasons": [],
"lockMessage": null,
"settingsProfile": "default",
"mobileWallet": {
"pushMessagingId": "c9wB0BakTaakW9vwtDIyl_:APA91bH-0-ArJEbYdV9s8m-6332wXfvO1DLYeoZzkkqasU3s-1893KdLarFdM7dJBHsb22H4lOFI4Xr_PzE9bFS2w",
"productModel": "SM-A415F",
"os": "ANDROID",
"deviceIdType": "ANDROID_ID",
"secretFingerprint": "0x83ec6a38e8cd9f12bc1ed89e771ca402048959e738943dAAAAAAAA",
"lastEligibilityCheck": "2023-11-15T10:04:50Z",
"nfc": true,
"deviceId": "c2032a73ac90de11",
"appBuildNumber": "v04-04-06-06-02-02",
"productFingerprint": "samsung/a41eea/a41:12/SP1A.210812.016/A415FXX123456:user/release-keys",
"mobileUpdateDate": "2023-11-15T10:04:50Z",
"appleTeamId": null,
"emulator": false,
"pushMessagingProvider": "FIREBASE",
"osVersion": "12",
"root": "0",
"sdkVersion": "2.4.11",
"brand": "samsung"
},
"activationCode": null,
"creationDate": "2023-07-13T15:29:05+02:00",
"deletionDate": null,
"activationCodeExpiryDate": "2023-07-13T15:49:05+02:00",
"authenticationMethods": [
{
"type": "DEVICE_BIOMETRIC",
"usages": [
"STRONG_CUSTOMER_AUTHENTICATION"
],
"parameters": {
"validityDuration": 60
}
},
{
"type": "HYBRID_PIN",
"usages": [
"WALLET_MANAGEMENT",
"STRONG_CUSTOMER_AUTHENTICATION"
],
"parameters": {
"maxAttempts": 3,
"validityDuration": 60
}
},
{
"type": "NONE",
"usages": [
"STRONG_CUSTOMER_AUTHENTICATION"
],
"parameters": []
},
{
"type": "CLOUD_PIN",
"usages": [
"WALLET_MANAGEMENT",
"STRONG_CUSTOMER_AUTHENTICATION"
],
"parameters": {
"maxAttempts": 3,
"validityDuration": 60
}
}
],
"invalidActivationAttempts": null,
"userId": "3400118",
"scaWalletTag": "Iphone 13 mini",
"clientId": "string",
"activationDate": "2023-07-15T15:29:05+02:00"
}
Key attributes
Status (status
)
Status | Description |
---|---|
CREATING | SCA Wallet is being created |
CREATED | SCA Wallet has been created, but has not yet been initialized |
INITIALIZING | SCA Wallet is being initialized |
ACTIVE | SCA Wallet has been initialized and is not locked or deleted |
DELETED | SCA Wallet has been deleted by issuer |
Sub Status (subStatus
)
Sub Status | Description |
---|---|
CREATING_IN_PROGRESS | SCA Wallet is being created |
CREATED_BLOCKED | SCA Wallet created but may not be used yet |
CREATED_READY | SCA Wallet created that can be used |
INITIALIZING_MOBILE | SCA Wallet is being initializing by the mobile |
ACTIVATED_LOGGED_IN | User is logged in |
ACTIVATED_LOGGED_OUT | User is logged out |
DELETED_BY_ISSUER | SCA Wallet has been deleted by the issuer |
DELETED_UNINSTALLED | SCA Wallet has been deleted because the SCA wallet has been uninstalled |
Passcode Status (passcodeStatus
)
Passcode Status | Description |
---|---|
SET | Passcode was set by the customer |
NOT_SET | Passcode was not set by the customer |
TO_BE_CHANGED | Passcode has to be changed |
NONE | None |
Locking Reasons (lockReason
)
Lock Reason | Description |
---|---|
ISSUER | You locked the SCA Wallet (generic lock reason) |
LOST_DEVICE | End User declared a lost device |
STOLEN_DEVICE | End User declared a stolen device |
FRAUDULENT_USE_SUSPECTED_BY_ISSUER | You suspected a fraudulent use of the SCA Wallet |
FRAUDULENT_USE_SUSPECTED_BY_CLIENT | End User suspected a fraudulent use of the SCA Wallet |
TERMINATE_SERVICE | Your business relation with the End User was terminated |
INCIDENT | Technical incident |
Note – You may encounter some locking reasons that can't be set manually
PASSCODE
– The end user entered too many wrong PIN codesPAYMENT
– The end user entered too many wrong PIN codes during a payment SCADELETED
– The SCA Wallet was deleted