Skip to content

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:

DeviceLimits
Mobile1 active SCA Wallet per device.
Web browser5 active SCA Wallets per device.

If these limits are exceeded, an HTTP error is returned.

Warning icon

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.

AttributeTypeDescription
webauthnstringThe PublicKeyCredential after the WebAuthn Register, encoded in base64.
passcodestringRequired 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 icon

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.

AttributeTypeDescription
userIdstringThe unique identifier of the user the SCA Wallet is to be attached to.
scaWalletTagstringCustom value for the SCA Wallet. Can be used to name the device for which the new SCA Wallet is created. Max length: 256 characters.
authMethodarrayThe 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.
scastringFor the Web Native solution, when creating the SCA Wallet as an end user (required if no authMethod is provided).
webauthnstringFor the Web Native solution. The PublicKeyCredential after the WebAuthn Register, encoded in base64.
passcodestringRequired 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:

Note icon

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:

  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.

AttributeTypeDescription
removeScaWalletId stringThe unique identifier of the SCA Wallet that is to be deleted.
swapReason stringThe reason for swapping SCA Wallet. Can be: LOST, STOLEN, or OTHER.
authMethodarrayThe 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.
scastringThe valid proof that authenticated the swap.
Required if no authMethod is provided.
scaWalletTagstringCustom 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.
Warning icon

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)

StatusDescription
CREATINGSCA Wallet is being created
CREATEDSCA Wallet has been created, but has not yet been initialized
INITIALIZINGSCA Wallet is being initialized
ACTIVESCA Wallet has been initialized and is not locked or deleted
DELETEDSCA Wallet has been deleted by issuer

Sub Status (subStatus)

Sub StatusDescription
CREATING_IN_PROGRESSSCA Wallet is being created
CREATED_BLOCKEDSCA Wallet created but may not be used yet
CREATED_READYSCA Wallet created that can be used
INITIALIZING_MOBILESCA Wallet is being initializing by the mobile
ACTIVATED_LOGGED_INUser is logged in
ACTIVATED_LOGGED_OUTUser is logged out
DELETED_BY_ISSUERSCA Wallet has been deleted by the issuer
DELETED_UNINSTALLEDSCA Wallet has been deleted because the SCA wallet has been uninstalled

Passcode Status (passcodeStatus)

Passcode StatusDescription
SETPasscode was set by the customer
NOT_SETPasscode was not set by the customer
TO_BE_CHANGEDPasscode has to be changed
NONENone

Locking Reasons (lockReason)

Lock ReasonDescription
ISSUERYou locked the SCA Wallet (generic lock reason)
LOST_DEVICEEnd User declared a lost device
STOLEN_DEVICEEnd User declared a stolen device
FRAUDULENT_USE_SUSPECTED_BY_ISSUERYou suspected a fraudulent use of the SCA Wallet
FRAUDULENT_USE_SUSPECTED_BY_CLIENTEnd User suspected a fraudulent use of the SCA Wallet
TERMINATE_SERVICEYour business relation with the End User was terminated
INCIDENTTechnical incident
Note icon

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

EndpointScope
/core-connect/sca/scawalletslegal, read_write
/core-connect/sca/scawallets/swapread_write
/core-connect/sca/scawallets?userId={userId}read_only
/core-connect/sca/scawallets/{scaWalletId}read_only
/core-connect/sca/scawallets/{scaWalletId}/resetPinlegal
/core-connect/sca/scawallets/{scaWalletId}/locklegal
/core-connect/sca/scawallets/{scaWalletId}/unlocklegal
/core-connect/sca/scawallets/{scaWalletId}legal