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 , bankaccountId , 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:
|
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.
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
{
"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
{
"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
withPUT /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.
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
{
"resourcesIds":["54321", "12345"],
}
Returns the External Operation object if successful, with the updated list of resourceIds
.
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
{
"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 |