Treezor Doc

# Introduction

Strong Customer Authentication (SCA) (opens new window) is a European regulatory requirement aiming at reducing fraud and making payments more secure.

As a Treezor client, you are using Treezor's ACPR agreement and must therefore implement SCA into your Users flow by either:

# Key concepts

To ensure a Strong Customer Authentication, we use at least 2 of the following 3 elements:

  • Something the User has (smartphone, hardware token...)
  • Something the User is (fingerprint, facial id)
  • Something the User knows (password, PIN)

SCA can be required in the following scenarios:

  • Per session: When logging-in, the User is required to use SCA which allows for some follow up actions without an additional SCA
  • Per operation: When doing a sensitive operation, the User is required to use SCA to confirm it

SCA aims to prove that the operation effectively originates from the User by:

  • Generating a cryptographic signature known as SCA Proof (JWS) of the requested operation on the User's device.
  • Sending this SCA proof to the Treezor API along with the normal operation request (such as creating a Beneficiary).
  • Checking the received SCA proof by the Treezor API and only allowing the operation if it is legitimate.

Treezor provides a mobile SDK and an abstraction layer to produce these cryptographic signatures.

# Authentication

Previously, all your requests to the Treezor API where made using the same authentication token.

To leverage the SCA mechanism, your requests to the Treezor API will have to be made in the name of each end user, using a distinct authentication token.

This is accomplished by:

  • Obtaining an SCA Proof in the form of a JWS (Json Web Signature) using the Mobile SDK on the End User's device
  • Providing this SCA Proof and a different grant type when requesting a JWT.
  • Using this JWT to authenticate all future requests to the Treezor API made in the name of that End User

💡 Depending on the type of SCA Proof provided, the JWT will contain a trz:sca attribute values to

  • false if the provided SCA was of type None.
  • true if any stronger type of authentication was used (Biometry, Passcode, etc.).

💡 If in the last 180 days, no authentication using an SCA type != of None happened, the End User is required to authenticate using a stronger SCA type such as Biometry, Passcode, etc.

The authentication payload is structured as follows.

# Parameters

Parameter Description
client_id The client_id as per your usual authentication flow.
client_secret The client_secret as per your usual authentication flow.
username The userId or the end user's email, as used in User objects
password A hash to be generated by concatenating userId with client_secret and hashing the string using sha256 i.e., sha256(userId + client_secret).
grant_type Must be set to delegated_end_user.
sca The SCA proof (which can be generated using a type None if a stronger type was used in the last 180 days).

In return, Treezor provides you with a JWT that must be used for all subsequent requests to the Treezor API made in the name of that User.

It must be placed in the Authorization: Bearer header as per normal authentication with Connect.

# Typical flow

The following diagram illustrates what is required of your Mobile App and back end to enforce Strong Customer Authentication.

Info icon

Information – The diagram is not exhaustive

For brevity, the diagram doesn't cover:

# Sessions

A session means that the User's requests to the Treezor API are authenticated using a JWT which:

  • Has been obtained with an SCA of type != None (JWT contains a trz:sca attribute valued to true).
  • Is not expired (in practice, this means that it has been obtained in the last 60 minutes as JWT has a 60-minute lifetime)
  • Has been used in the last 5 minutes to make any valid call to the Treezor API.
Note icon

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 an HTTP Status Code 401

# Flows

# Per Operation

When a request to the Treezor API mandates a per-operation SCA

  • You prepare the necessary API payload for the desired endpoint as usual
  • You sign the payload using the User's private key, this produces a unique signature (accomplished using the SDK)
  • You send the payload along with the signature to the Treezor API (the endpoints don't change)
    • For requests using GET, DELETE you add the signature as a sca queryParam
    • For requests using PUT, POST you add the signature as a sca attribute into the payload itself
  • Treezor checks the payload against the provided signature and the User's public key
    • ✅ If the signature is valid, the request is handled by Treezor
    • ❌ If the signature is invalid or missing, the request is rejected by Treezor with a 400 Status Code

The signing steps are accomplished using our Partner's SDK.

You will provide your Payload to the SDK along with the desired authentication method (PIN or BIOMETRIC). In return, the SDK will provide you with the payload's signature. This signed payload is known as SCA proof and takes the form of a JWS (JSON Web Signature).

# Per Session

For other requests to the Treezor API

  • You request an SCA proof using the SDK
  • You provide this SCA proof when authenticating against the Treezor API
  • Treezor checks the signature
    • ✅ If the signature is valid and used an SCA type different from None, we deliver a JWT containing an trz:sca valued to true
    • ✅ If the signature is valid and used an SCA type None, we deliver a JWT containing an trz:sca valued to false
    • ❌ If the signature is invalid, no JWT is delivered
  • You authenticate all future requests using this JWT.
Updated on: 5/2/2024, 1:05:54 PM

← Endpoints & Data →