Skip to content

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.

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).

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

EndpointNote
/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/operationsOnly for operations that are more than 90 days old
/v1/transfersOnly if beneficiaryWalletId belongs to the current User

Per Operation

EndpointData 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/beneficiariesuserId, name, address, iban, bic, usableForSctPayload example
/v1/beneficiaries/{beneficiaryId}nickName, name, iban, bic, usableForSct, isActive
/v1/cardimagescardIdPayload example
/v1/cards/{cardId}/ActivatePayload example
/v1/cards/{publicToken}/public-token-activation
/v1/cards/{cardId}/ChangePIN
/v1/cards/{cardId}/setPIN
/v1/cards/{cardId}/UnblockPIN
/v1/cards/{cardId}/LockUnlocklockStatusOnly when unlocking (lockStatus is 0)
/v1/cards/{cardId}/LimitslimitAtmYear, limitAtmMonth, limitAtmWeek, limitAtmDay, limitAtmAll, limitPaymentYear, limitPaymentMonth, limitPaymentWeek, limitPaymentDay, limitPaymentAll, paymentDailyLimit, restrictionGroupLimitsPayload example
/v1/cards/{cardId}/Optionsforeign, online, atm, nfc
/v1/issuerInitiatedDigitizationDatascardId, tokenRequestor, additionnalData
/v1/cardDigitalizations/{cardDigitalizationId}status, reasonCodeOnly if the status is unsuspend
/v1/payoutwalletId, amount, currency, bankaccountId, beneficiaryId
/core-connect/scheduledPaymentwalletId, beneficiaryType, beneficiary, beneficiaryLabel, amount, type, execAt, startAt, endAt, period, currency, scheduledPaymentName, endToEndId
/v1/transferswalletId, beneficiaryWalletId, amount, currency, transferTypeIdOnly if beneficiaryWalletId doesn't belong to the current User
/v1/users/{userId}phone, mobile, email, address1, address2, address3, postcode, city, state, country, countryNameOnly if phone, mobile, email, or any of the address attributes are modified.
Payload example
Thumbs icon

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:

AttributeTypeDescription
externalOperationIdstring32-character long identifier of the External Operation the database (UUIDv4).
actionNamestringThe end user action that was secured by an SCA. See list of actions.
scaProofstringThe valid proof that authenticated the end user's action.
actionDatestringThe date on which the declared action took place.
resourceIdsarrayThe 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
createdAtstringThe date and time at which the External Operation was created.
scaDatestringThe iat timestamp of the scaProof for per-operation SCA.
amrstringThe type of SCA for per-operation SCA (e.g., CLOUD_PIN, HYBRID_PIN, DEVICE_BIOMETRIC)
externalOperationNotestringComment 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:

actionNameDescriptionSession
externalGetBalanceRetrieve the wallet balancePer-session (180 days exempt.)
externalOperationView90DaysRetrieve the operations history for the last 90 daysPer-session (180 days exempt.)
externalOperationViewRetrieve the operations history for operations older than 90 daysPer-session
externalDisplayAccountDetailsRetrieve information about the Wallet (i.e., account details)Per-session
externalGetStatementRetrieve the Account Statement (i.e., operations for a given month)Per-session
externalMassPayoutOrderCreationCreation of a transfer order for a mass payoutPer-operation
externalMassTransferOrderCreationCreation of a transfer order for a mass transferPer-operation
externalScheduledPayoutOrderCreation of a transfer order for a scheduled or recurring payoutPer-operation
externalScheduledTransferOrderCreation of a transfer order for a scheduled or recurring transferPer-operation
externalUpdateLimitsCardUpdate of the card limits externally.Per-operation
internalCheckDeclare 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.

externalOperationNoteDescription
Wrong sca valueThe JWT trz:sca is not to true
Wrong JWT. Grant type must be delegated end userThe JWT userType is not user
Parse errorThe SCA proof is not readable
Wrong certificateThe SCA proof certificate is not valid
Signature errorThe SCA proof is not signed
AMR not allowedThe SCA proof amr is not allowed
Declaration delay is too longThe 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:

  1. Declare your External Operation with POST /core-connect/sca/externalOperations
  2. 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.

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

EndpointScope
/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