Endpoints & Data

Functional context

Whether or not you use Treezor SCA endpoints, you're legally required to declare the end users actions. Strong customer authentication must occur on the following functional requests.

Per-session operations with 180 days exemption

The following actions can be done if a session with an SCA (!= None) was used in the last 180 days:

Logging into the customer space
Checking the Balance of Wallets
Checking the Operations history of the last 90 days

Per-session operations

The following actions can be done if this very session was opened using an SCA (!= None), and if the session is still active.

Ordering a new Card
Searching for operations
Checking or downloading Account Statements
Transferring funds between Wallets belonging to the same User
Displaying bank account details
Self-certifications (such as defining a tax residence, etc.)

If the session is no longer active or if this is the first time the user is authenticating, then a new session must be open with an SCA (!= None).

Individual operations

For all the following operations, a per-operation SCA is required (regardless of the use of an SCA during initial authentication and session opening).

Displaying a Card information (PAN, CVV, etc.)
Modifying a PIN, displaying a PIN or unlocking a PIN.
Updating personal information (mobile phone, email, address)
Adding or changing a Beneficiary
Creating a SEPA transfer (SCTE)
Transferring funds between Wallets belonging to distinct Users

Creating a SEPA Mandate
Enrolling a Card into X-Pay
Approving an online payment with a Card (e-commerce)
Changing a Card payment or withdrawal limits
Changing a Card restrictions or options
Activating a Card
Initiating recurring payments or mass payments

Applying SCA with Treezor services

You must provide an SCA proof anytime you use a Treezor API request that falls into the functional context of Strong Customer Authentication. This proof of SCA is to be presented in a specific way (i.e., data to sign in the path and payload), as listed in the endpoints requiring SCA in the table below.

You may also:

Find badges across the documentation, notifying you of the need for an SCA.
Check out the Regulatory Technical Standards for an exhaustive and authoritative list of operations requiring SCA.

Per Session

Endpoint	Note
`/v1/cards/CreateVirtual`
`/v1/cards/RequestPhysical`
`/core-connect/card/bulk`
`/v1/taxResidences`
`/v1/taxResidences/{taxResidenceId}`
`/v1/wallets`
`/core-connect/account-details/{walletId}/raw`
`/core-connect/account-details/{walletId}/computed`
`/core-connect/statements/{walletId}/raw`
`/core-connect/statements/{walletId}/computed`
`/core-connect/operations`	Only for operations that are more than 90 days old
`/v1/transfers`	Only if `beneficiaryWalletId` belongs to the current User

Per Operation

Endpoint	Data to sign in the SCA proof `body` (only if present in the payload)	Note
`/v1/auth-requests/{authRequestId}/result`
`/v1/bankaccounts`	`userId`, `bankaccountOwnerName`, `bankaccountOwnerAddress`, `bankaccountIBAN`, `bankaccountBIC`, `bankaccountType`
`/v1/beneficiaries`	`userId`, `name`, `address`, `iban`, `bic`, `usableForSct`	Payload example
`/v1/beneficiaries/{beneficiaryId}`	`nickName`, `name`, `iban`, `bic`, `usableForSct`, `isActive`
`/v1/cardimages`	`cardId`	Payload example
`/v1/cards/{cardId}/Activate`		Payload example
`/v1/cards/{publicToken}/public-token-activation`
`/v1/cards/{cardId}/ChangePIN`
`/v1/cards/{cardId}/setPIN`
`/v1/cards/{cardId}/UnblockPIN`
`/v1/cards/{cardId}/LockUnlock`	`lockStatus`	Only when unlocking (`lockStatus` is `0`)
`/v1/cards/{cardId}/Limits`	`limitAtmYear`, `limitAtmMonth`, `limitAtmWeek`, `limitAtmDay`, `limitAtmAll`, `limitPaymentYear`, `limitPaymentMonth`, `limitPaymentWeek`, `limitPaymentDay`, `limitPaymentAll`, `paymentDailyLimit`, `restrictionGroupLimits`	Payload example
`/v1/cards/{cardId}/Options`	`foreign`, `online`, `atm`, `nfc`
`/v1/issuerInitiatedDigitizationDatas`	`cardId`, `tokenRequestor`, `additionnalData`
`/v1/cardDigitalizations/{cardDigitalizationId}`	`status`, `reasonCode`	Only if the `status` is `unsuspend`
`/v1/payout`	`walletId`, `amount`, `currency`, `beneficiaryId`
`/core-connect/scheduledPayment`	`walletId`, `beneficiaryType`, `beneficiary`, `beneficiaryLabel`, `amount`, `type`, `execAt`, `startAt`, `endAt`, `period`, `currency`, `scheduledPaymentName`, `endToEndId`
`/v1/transfers`	`walletId`, `beneficiaryWalletId`, `amount`, `currency`, `transferTypeId`	Only if `beneficiaryWalletId` doesn't belong to the current User
`/v1/users/{userId}`	`phone`, `mobile`, `email`, `address1`, `address2`, `address3`, `postcode`, `city`, `state`, `country`, `countryName`	Only if `phone`, `mobile`, `email`, or any of the `address` attributes are modified. Payload example

Best practice – Optimize user experience by avoiding subsequent calls on per-operation SCA endpoints

When an action on your application requires several calls to per-operation SCA endpoints, the user goes through multiple SCA in a row. Split your sensitive actions on your mobile app for a better experience.

Example

If your mobile application allows to change a Card limits (PUT /v1/cards/{cardId}/Limits) and Options (PUT /v1/cards/{cardId}/Options) at the same time and on the same screen, that would require two sequential SCA operations on the mobile.

To avoid this, you could offer to change Options and Limits on different screens of your application.

Declaring SCA External Operations

When applying SCA outside of Treezor services, you are legally required to declare the listed end user actions to Treezor. Treezor uses these declarations for reporting to the regulator.

The External Operations endpoint allows you to declare any sensitive action that:

Required a Strong Customer Authentication (SCA) and,
Was made from your back end (rather than Treezor's)

Key attributes

Below are the most important External Operation attributes:

Attribute	Type	Description
`externalOperationId`	string	32-character long identifier of the External Operation the database (UUIDv4).
`actionName`	string	The end user action that was secured by an SCA. See list of actions.
`scaProof`	string	The valid proof that authenticated the end user's action.
`actionDate`	string	The date on which the declared action took place.
`resourceIds`	array	The list of unique identifiers (strings) of the objects, conditioned by the type of action: walletId for `externalGetStatement`, `externalGetBalance`, `externalOperationView`, `externalOperationView90Days`, and `externalDisplayAccountDetails` payoutId for transferId in case of a payout or transfer cardId for `externalUpdateLimitsCard`
`createdAt`	string	The date and time at which the External Operation was created.
`scaDate`	string	The `iat` timestamp of the `scaProof` for per-operation SCA.
`amr`	string	The type of SCA for per-operation SCA (e.g., `CLOUD_PIN`, `HYBRID_PIN`, `DEVICE_BIOMETRIC`)
`externalOperationNote`	string	Comment left by Treezor after scoring, indicating a potential issue. See List of notes.

Action names (`actionName`)

The actionName parameter is required to declare an SCA External Operation. It can be one of the following:

`actionName`	Description	Session
`externalGetBalance`	Retrieve the wallet balance	Per-session (180 days exempt.)
`externalOperationView90Days`	Retrieve the operations history for the last 90 days	Per-session (180 days exempt.)
`externalOperationView`	Retrieve the operations history for operations older than 90 days	Per-session
`externalDisplayAccountDetails`	Retrieve information about the Wallet (i.e., account details)	Per-session
`externalGetStatement`	Retrieve the Account Statement (i.e., operations for a given month)	Per-session
`externalMassPayoutOrderCreation`	Creation of a transfer order for a mass payout	Per-operation
`externalMassTransferOrderCreation`	Creation of a transfer order for a mass transfer	Per-operation
`externalScheduledPayoutOrder`	Creation of a transfer order for a scheduled or recurring payout	Per-operation
`externalScheduledTransferOrder`	Creation of a transfer order for a scheduled or recurring transfer	Per-operation
`externalUpdateLimitsCard`	Update of the card limits externally.	Per-operation
`internalCheck`	Declare a sensitive action that is not part of Treezor's Regulatory Technical Standard but that you want to secure with strong authentication.	Per-operation

Notes (`externalOperationNote`)

The externalOperationNote parameter displays information when there is an issue with your External Operation Declaration.

`externalOperationNote`	Description
`Wrong sca value`	The JWT `trz:sca` is not to `true`
`Wrong JWT. Grant type must be delegated end user`	The JWT `userType` is not `user`
`Parse error`	The SCA proof is not readable
`Wrong certificate`	The SCA proof certificate is not valid
`Signature error`	The SCA proof is not signed
`AMR not allowed`	The SCA proof `amr` is not allowed
`Declaration delay is too long`	The time elapsed between SCA proof and the `actionDate` is over 300 seconds

Declare an External Operation

In order to declare an SCA External Operation, you must use a JWT accessToken with a delegated_end_user grant type and the read_write scope. See the Authentication article for more information.

You can then use the following request to declare an external operation.

CURL

bash

curl -X POST {baseUrl}/core-connect/sca/externalOperations \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is a {payload} example:

JSON

json

{
	"actionName": "string",     // Required
	"scaProof": "string",       // Conditional
	"actionDate": "date",       // Required - RFC 3339
	"resourceIds":[""]          // Conditional depending on the actionName
}

Returns the External Operation object if successful.

JSON

json

{
    "externalOperationId":"7a5740ed-b1ae-4afd-940b-1193275728ab",
    "actionName":"externalScheduledTransferOrder",
    "scaProof":"[...]MJsrki4orRnqQ",
    "actionDate":"2024-02-16T14:37:04+01:00",
    "resourceIds":[
        "12345",
        "67890"
    ],
    "createdAt":"2024-02-16T14:37:05+01:00",
    "scaDate":"2024-02-16T14:37:04+01:00",
    "amr":"HYBRID_PIN",
    "externalOperationNote":"",
    "externalOperationResponseCode":0       // For Treezor purposes only
}

Update an External Operation

You must update per-operation payment external operations in order to link all subsequent payments to the initial declaration.

For instance, for recurring or mass payments, the steps are the following:

Declare your External Operation with POST /core-connect/sca/externalOperations
When the corresponding payments are created, update your external Operation by adding the id with PUT /core-connect/sca/externalOperations/{externalOperationId}

Each recurring payment must be declared and linked to the original External Operation declaration. In the case of mass payments, all the payment ids must be declared when updating the External Operation.

Use the following request to update an External Operation declaration.

CURL

bash

curl -X PUT {baseUrl}/core-connect/sca/externalOperations/{externalOperationId} \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is a {payload} example:

JSON

json

{
  "resourcesIds":["54321", "12345"],
}

Returns the External Operation object if successful, with the updated list of resourceIds.

JSON

json

{
    "externalOperationId":"7a5740ed-b1ae-4afd-940b-1193275728ab",
    "actionName":"externalScheduledPayoutOrder",
    "scaProof":"[...]MJsrki4orRnqQ",
    "actionDate":"2024-02-16T14:37:04+01:00",
    "resourceIds":[
        "54321",
        "12345"
    ],
    "createdAt":"2024-02-16T14:37:05+01:00",
    "scaDate":"2024-02-16T14:37:04+01:00",
    "amr":"HYBRID_PIN",
    "externalOperationNote":"",
    "externalOperationResponseCode":0       // For Treezor purposes only
}

Structure of an External Operation

JSON

json

{
    "externalOperationId":"7a5740ed-b1ae-4afd-940b-1193275728ab",
    "actionName":"externalScheduledPayoutOrder",
    "scaProof":"[...]MJsrki4orRnqQ",
    "actionDate":"2024-02-16T14:37:04+01:00",
    "resourceIds":[
        "12345",
        "67890"
    ],
    "createdAt":"2024-02-16T14:37:05+01:00",
    "scaDate":"2024-02-16T14:37:04+01:00",
    "amr":"HYBRID_PIN",
    "externalOperationNote":"",
    "externalOperationResponseCode":0       // For Treezor purposes only
}

External Operation Endpoints

Endpoint	Scope
`/core-connect/sca/externalOperations` Create an SCA External Operation Declaration	`read_write`
`/core-connect/sca/externalOperation/{externalOperationId}` Update an SCA External Operation Declaration	`read_write`

Endpoints & Data ​

Functional context ​

Per-session operations with 180 days exemption ​

Per-session operations ​

Individual operations ​

Applying SCA with Treezor services ​

Per Session ​

Per Operation ​

Declaring SCA External Operations ​

Key attributes ​

Action names (actionName) ​

Notes (externalOperationNote) ​

Declare an External Operation ​

Update an External Operation ​

Structure of an External Operation ​

External Operation Endpoints ​

Endpoints & Data

Functional context

Per-session operations with 180 days exemption

Per-session operations

Individual operations

Applying SCA with Treezor services

Per Session

Per Operation

Declaring SCA External Operations

Key attributes

Action names (`actionName`)

Notes (`externalOperationNote`)

Declare an External Operation

Update an External Operation

Structure of an External Operation

External Operation Endpoints