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.

CURL

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.

CURL

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.

CURL

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.

CURL

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.

CURL

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.

CURL

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.

CURL

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

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:

1. The previous SCA Wallet is deleted (i.e., its status is set to DELETED).
2. A new SCA Wallet is created, and will be activated and/or usable on the new device.
3. 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;

CURL

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

CURL

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.

CURL

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 codes
• PAYMENT – The end user entered too many wrong PIN codes during a payment SCA
• DELETED – The SCA Wallet was deleted

Endpoints

Endpoint	Scope
/core-connect/sca/scawallets	legal, read_write
/core-connect/sca/scawallets/swap	read_write
/core-connect/sca/scawallets?userId={userId}	read_only
/core-connect/sca/scawallets/{scaWalletId}	read_only
/core-connect/sca/scawallets/{scaWalletId}/resetPin	legal
/core-connect/sca/scawallets/{scaWalletId}/lock	legal
/core-connect/sca/scawallets/{scaWalletId}/unlock	legal
/core-connect/sca/scawallets/{scaWalletId}	legal