Securing endpoints

Functional context

If you're eligible to SCA, you're legally required to declare the end users actions, regardless of whether they are done with Treezor endpoints or with your own back end.

The actions requiring SCA can be broken down into 3 categories:

• Passive session actions
• Active session actions
• Individual actions

A session means that the requests of the end user to the Treezor API are authenticated using a JWT which:

• Was obtained with an SCA of type != None (JWT with a trz:sca valued to true).
• Is not expired (i.e., obtained in the last 60 minutes as JWT have a 60-minute lifetime)
• Was used in the last 5 minutes to make any valid call to the Treezor API.

Note – Session expiration after 5 minutes

Even if the JWT itself hasn't expired yet, if it has not been used in the last 5 minutes to call Treezor API the SCA session is considered expired.

If the session has expired, the following error will be returned by the API with a 401 HTTP Status Code.

JSON

{
    "errors": [
        {
            "type": "invalid_request",
            "code": "sca_session_expired",
            "message": "Your session has expired.",
            "docUrl": "string"
        }
    ]
}

Passive session actions

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

Active session actions

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
• Transferring funds between Wallets belonging to the same User
• Searching for operations
• Checking or downloading Account Statements
• 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 actions

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

• Activating a Card
• Approving an online payment with a Card (e-commerce)
• Displaying a Card information (PAN, CVV, etc.)
• Enrolling a Card into X-Pay
• Changing a Card payment or withdrawal limits
• Changing a Card restrictions or options
• Modifying a PIN, displaying a PIN or unlocking a PIN
• Updating personal information (mobile phone, email, address)
• Transferring funds between Wallets belonging to distinct Users
• Adding or changing a Beneficiary
• Creating a SEPA transfer (SCTE)
• Creating a SEPA Mandate
• Initiating recurring payments or mass payment

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, indicating 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

In your application, changing both the Card limits (PUT /v1/cards/{cardId}/Limits) and options (PUT /v1/cards/{cardId}/Options) at the same time and on the same screen requires 2 sequential SCA operations. This means your end user has to go through SCA twice.

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

SCA for Card Transactions

When eligible to SCA, most card transactions must be authenticated. Therefore, the steps of a card transaction are the following:

1. Authentication – Ensuring the legitimate cardholder is initiating the transaction.
2. Authorization – Checking the balance, limits, restrictions, etc. to accept the transaction.
3. Transaction – Moving the funds from the cardholders' account.

For the authentication step to be properly SCA-compliant, you must:

• Enroll the user card for OOB authentication
• Ensure your handle card transaction authentication properly

Please note that the 3D Secure (3DS) protocol on its own is not SCA-compliant. It is used as a fallback option only.

Card authentication methods enrollment

Cards must be registered with the 2 following methods to accept secure online payments:

Method	Endpoint
Out of Band (OOB)	/v1/cards/{cardId}/authentication-methods A strong customer authentication of the cardholder through their payment application.
SMS method	/v1/cards/Register3DS Fallback with a one-time password (OTP) sent by SMS.

Tip – Cards are enrolled with both methods at the same time

This allows you to request a FALLBACK to the SMS method if the Out of Band authentication is not possible during a card transaction.

Enrolling to Out of Band Authentication

When a User has an active (provisioned) SCA Wallet, you must enable the SCA for a Card using the following request.

CURL

curl -X POST {baseURL}/v1/cards/{cardId}/authentication-methods \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content: application/json' \
	-d '{
		"method": "OOB"
	}'

Returns an HTTP 201 response.

JSON

{
    "publicToken": "103685666",
    "id": "b7478da6-4165-4c8c-xxx0-8e9200f5162a",
    "method": "OOB",
    "system": "GPS"
}

Retrieving a Card authentication methods

CURL

curl -X GET {baseURL}/v1/cards/{cardId}/authentication-methods \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content: application/json' \

Returns the Card enrollments list.

JSON

[
    {
        "publicToken": "103685965",
        "id": "2739879",
        "method": "OTPSMS",
        "system": "GPS"
    },
    {
        "publicToken": "103685965",
        "id": "b7478da6-4165-4c8c-aaa0-8e9200f5162a",
        "method": "OOB",
        "system": "GPS"
    }
]

Enrolling to fallback SMS Authentication

3D Secure provides an enhanced level of security for online (e-commerce) payments by adding the possibility to authenticate the cardholder. Registering the card for 3D Secure requires a mobile phone number. The cardholder will then be sent a secure code on their mobile phone when an authentication is required for an online payment. This code is unique for each payment and needs to be entered on the merchant's website or mobile application when prompted.

Prior to this step, your must ensure the User was created with a mobile phone number. Otherwise, the User must be updated with a mobile phone number.

CURL

curl -X POST {baseUrl}/v1/cards/Register3DS \
    --header 'Authorization: Bearer {accessToken}' \
    --header 'Content-Type: application/json' \
    -d '{
        "cardId": 123456
    }'

This returns a Card object, but doesn't specify the 3D Secure enrolling status. Treezor also sends a card.register3DS webhook.

Configuration – By default, 3DS SMS are sent under the name "Secure3DS"

You can contact Treezor and provide a new sender name that:

• Contains only alphanumeric characters (no spaces)
• Starts with a letter
• Is less than 12-character long

3DSecure enrollment endpoints

Find below the list of 3DSecure endpoints (SCA Mode).

Endpoint	Description
/v1/cards/{cardId}/authentication-methods	Define the authentication methods of a Card
/v1/cards/{cardId}/authentication-methods	Retrieve the authentication methods of a Card
/v1/cards/{cardId}/authentication-methods/{authMethodId}	Retrieve details regarding the authentication method of a Card
/v1/cards/{cardId}/authentication-methods/{authMethodId}	Delete the authentication method of a Card. Only available for OOB method.

Card transactions authentication

When a Card Transaction goes through SCA, the following occurs:

1. Treezor notifies you by sending a card3DSv2Authentication.create webhook.
2. You authenticate your end user using the SDK and an SCA method.
3. You inform Treezor of the authentication result using the dedicated endpoint.
4. Treezor notifies you of the final transaction status by sending a card3DSv2Authentication.update webhook.

Reading – Article dedicated to Card transaction SCA

Learn more in the Transactions authentication (SCA) article.

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 SCA Authentication article for more information.

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

CURL

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 /core-connect/sca/externalOperations
2. When the corresponding payments are created, update your external Operation by adding the id with /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

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
}

External Operation object

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