Skip to main content

REDIRECT channel definitions roll out

API v2.1 was introduced to handle PSD2 requirements. The changes brought by this API version are described here.

REDIRECT channel definitions, responsible for interactions with PSD2 APIs will be enabled ASPSP by ASPSP (or set of ASPSPs by set of ASPSPs).

You will find below the different phases we will follow when we will enable the REDIRECT channel definition for one ASPSP (one provider in our API). For each phase, we will describe what will happen for new connections and existing connections.

Note that depending on schedule and/or compliance needs, the first step described below could be skipped for some of the providers. This would also prevent using user batches, see below.

Here is an overview of what you'll find in this section:

Initial State : EMBEDDED channel definitions only​

Initially, a provider has only an EMBEDDED channel definition. This channel definition covers all the account types our API currently supports: CHECKINGS, CREDIT_CARD, SAVINGS, LOAN.

Example:

{ "id": "87", "name": "Linxo Test Bank", "base_url": "https://wwws.linxo.com", "logo_url": "https://static.linxo-connect.io/common/pictures/providers_logos/87.png", "country_code": "FRA", "channel_definitions": [ { "id": "8700", "mode": "EMBEDDED", "account_types": [ "CHECKINGS", "CREDIT_CARD", "SAVINGS", "LOAN" ], "interactive": true, "credentials": [ { "id": "300", "label": "User ID", "label": "User ID", "label": "User ID", "type": "TEXT", "encrypt": false, "regexp": "." }, { "id": "301", "label": "Password", "type": "PWD", "encrypt": true, "regexp": "." }, { "id": "302", "label": "Accounts file location", "type": "TEXT", "encrypt": false, "regexp": ".*" } ], "unavailable": false, "capabilities": [ "PFM_ACCOUNT" ] } ] }

Initial State : New connections​

In initial state, a new connection can only be created with an EMBEDDED channel. All the accounts will be linked to this channel.

Initial State : Existing connections​

Existing connections will also have an EMBEDDED channel only. And all the accounts will also be linked to this channel.

Step 1 : enabling REDIRECT channel definitions, without stopping PSD2 accounts scraping​

To switch to this step, we will enable a REDIRECT channel definition for the provider. This channel definition will cover PSD2 account types: CHECKINGS and CREDIT_CARD.

The EMBEDDED channel definition will still cover all the account types our API currently supports: CHECKINGS, CREDIT_CARD, SAVINGS, LOAN.

So CHECKINGS and CREDIT_CARD accounts are still available through both channel definitions. This is to materialize that at this step, we will not stop scraping PSD2 accounts for existing connections (see below).

Example:

{ "id": "87", "name": "Linxo Test Bank", "base_url": "https://wwws.linxo.com", "logo_url": "https://static.linxo-connect.io/common/pictures/providers_logos/87.png", "country_code": "FRA", "channel_definitions": [ { "id": "8701", "mode": "REDIRECT", "account_types": [ "CHECKINGS", "CREDIT_CARD" ], "interactive": false, "credentials": [ { "id": "870100", "label": "Authorization code", "type": "AUTHORIZATION_CODE", "encrypt": false, "regexp": "." }, { "id": "870101", "label": "Access token", "type": "ACCESS_TOKEN", "encrypt": false, "regexp": "." }, { "id": "870102", "label": "Refresh token", "type": "REFRESH_TOKEN", "encrypt": false, "regexp": ".*" }, { "id": "870103", "label": "State", "type": "STATE", "encrypt": false, "regexp": ".+" } ], "unavailable": false, "capabilities": [ "PFM_ACCOUNT" ] }, { "id": "8700", "mode": "EMBEDDED", "account_types": [ "CHECKINGS", "CREDIT_CARD", "SAVINGS", "LOAN" ], "interactive": true, "credentials": [ { "id": "300", "label": "User ID", "type": "TEXT", "encrypt": false, "regexp": "." }, { "id": "301", "label": "Password", "type": "PWD", "encrypt": true, "regexp": "." }, { "id": "302", "label": "Accounts file location", "type": "TEXT", "encrypt": false, "regexp": ".*" } ], "unavailable": false, "capabilities": [ "PFM_ACCOUNT" ] } ] }

Step 1 : New connections​

As noted above, in this step, CHECKINGS and CREDIT_CARD accounts are available through both channel definitions. It is the integrator's responsibility to encourage its users to create a REDIRECT channel first for PSD2 accounts.

In any case, if a user creates a REDIRECT channel first, CHECKINGS and CREDIT_CARD accounts will be linked to this channel. They will remain linked to this channel even if the user adds an EMBEDDED channel afterwards.

If a user creates an EMBEDDED channel first and then a REDIRECT channel, CHECKINGS and CREDIT_CARD accounts will be linked to the EMBEDDED channel until the REDIRECT channel is created. They will then be linked automatically to the REDIRECT channel and will remain linked to this channel.

The link between an account and a channel is specified in our API by the last_channel_definition_id field in the accounts resource. See GET /accounts/{id} endpoint.

Step 1 : Existing connections​

In this step, for existing connections, we do not stop scraping CHECKINGS and CREDIT_CARD accounts through the EMBEDDED channel until a user adds a REDIRECT channel.

As we enable the REDIRECT channel definition for a provider, a channel with an EMPTY status will appear in all existing connections of this provider. (This is not true if batches are used, see dedicated section below.) The presence of an EMPTY channel can be used by integrators to determine a user can add a channel for a channel definition.

Example:

{ "id" : "12345", "provider_id" : "87", "name" : "Linxo Test Bank", "status" : "SUCCESS", "creation_date" : 1576574221, "auto_sync" : true, "logo_url" : "https://static.linxo-connect.io/common/pictures/providers_logos/87.png", "channels" : [ { "channel_definition_id" : "8700", "mode" : "EMBEDDED", "expires" : 1584313200, "status" : "SUCCESS", "last_success_date" : 1579258386, "last_end_date" : 1579258386, "credentials" : [ ], "account_types" : [ "CHECKINGS", "CREDIT_CARD", "SAVINGS", "LOAN" ] }, { "channel_definition_id" : "8701", "mode" : "REDIRECT", "status" : "EMPTY", "account_types" : [ "CHECKINGS", "CREDIT_CARD" ] } ], "owner" : { "name" : "M. Jean Dupont" }, "consent_per_account" : false }

Note EMPTY channels are not limited to REDIRECT channel definitions. If a user creates a connection with a REDIRECT channel first, an EMPTY channel for the EMBEDDED channel definition will be present in the connection.

Step 1 and batches​

The step 1 does not have to be enabled for all users at once. It can be enabled by batch (of users). This section describes how the batches can be built and what will happen for users included in a batch and for new users.

Batches will be built this way:

  • a first batch of users, limited to 100 users, with a list of users communicated by the integrator
  • the rest of the users, split in 2 or 3 batches, with users selected randomly (no custom batch definition possible)

Note that:

  • only users with existing connections for the concerned provider can be included in a batch (the information of being part of a batch is held by a connection, not a user)
  • new users will be able to use the new channel only once the channel definition is opened to all the users (i.e. at the last batch)

A user included in a batch will be able:

  • to add a channel to an existing connection
  • to create a new connection using the new channel

Until the last batch, new users will not be able to use the new channel definition.

Step 2 : Stopping PSD2 accounts scraping​

In this final step, we will stop scraping PSD2 accounts through the EMBEDDED channels. This will be materialized in channel definition account types: the account types in the EMBEDDED channel definition will no longer contain CHECKINGS and CREDIT_CARD.

Example:

{ "id": "87", "name": "Linxo Test Bank", "base_url": "https://wwws.linxo.com", "logo_url": "https://static.linxo-connect.io/common/pictures/providers_logos/87.png", "country_code": "FRA", "channel_definitions": [ { "id": "8701", "mode": "REDIRECT", "account_types": [ "CHECKINGS", "CREDIT_CARD" ], "interactive": false, "credentials": [ { "id": "870100", "label": "Authorization code", "type": "AUTHORIZATION_CODE", "encrypt": false, "regexp": "." }, { "id": "870101", "label": "Access token", "type": "ACCESS_TOKEN", "encrypt": false, "regexp": "." }, { "id": "870102", "label": "Refresh token", "type": "REFRESH_TOKEN", "encrypt": false, "regexp": ".*" }, { "id": "870103", "label": "State", "type": "STATE", "encrypt": false, "regexp": ".+" } ], "unavailable": false, "capabilities": [ "PFM_ACCOUNT" ] }, { "id": "8700", "mode": "EMBEDDED", "account_types": [ "SAVINGS", "LOAN" ], "interactive": true, "credentials": [ { "id": "300", "label": "User ID", "type": "TEXT", "encrypt": false, "regexp": "." }, { "id": "301", "label": "Password", "type": "PWD", "encrypt": true, "regexp": "." }, { "id": "302", "label": "Accounts file location", "type": "TEXT", "encrypt": false, "regexp": ".*" } ], "unavailable": false, "capabilities": [ "PFM_ACCOUNT" ] } ] }

Step 2 : New connections​

For new connections, CHECKINGS and CREDIT_CARD accounts will only be available through the REDIRECT channel.

Step 2 : Existing connections​

For existing connections, CHECKINGS and CREDIT_CARD accounts will no longer be synchronized through the EMBEDDED channel. The PSD2 accounts will get UNAVAILABLE status. The EMBEDDED channel will get:

  • PARTIAL_SUCCESS status if the connection had SAVINGS or LOAN accounts, that would keep being synchronized
  • FAILED if the connection had only CHECKINGS and CREDIT_CARD accounts

Note that in this step as well, a REDIRECT channel with status EMPTY will be present in the connection until the user actually authenticates.

Step 2 and batches​

The second step cannot be enabled by batch. Stopping scraping PSD2 accounts through the EMBEDDED channels can only be done for a provider, globally, not user per user.

This also means that if for a given provider, the step 1 is skipped (for schedule and/or compliance reasons), there will be no batch mechanism possible.