Skip to main content

Working with providers and channels

Description#

PSD2 involvement#

PSD2 APIs introduces a new way of authenticating users to obtain credentials in order to access data for checkings and credit card accounts. These credentials are collected using a web redirect and expires after 90 days. The user will need to perform a strong customer authentication (SCA) with an SMS or a security device when he adds a new connection and when he renews its credentials.

The PSD2 bank API allows to recover the current accounts. For other accounts (savings, credit, investment), scraping is necessary. Consequently, to cover the entire functional scope of your application, you may still need to use the form based credentials (embedded mode) to collect the data not available via PSD2 API.

In the Oxlin environment, a bank connection has 2 types of none exclusive channels:

  • 'REDIRECT': corresponding to the DSP2 API type connection for payment accounts
  • 'EMBEDDED': corresponding to the 'scraping' type connection to get access to savings, credit accounts and eventually payment accounts when not supported in redirect by the bank

A sub structure called channel_definitions is defined in each provider and contains the credentials that belongs to the same authentication mode (parameter mode: 'REDIRECT' or 'EMBEDDED').

A channel_definition with a mode 'REDIRECT' will indicate that the user should be redirected on a web browser to perform an authentication on the provider's website before creating or updating a connection.

When creating a connection, we are defining one or more channels using the channel description in the provider. These channels represents the links between our service and the provider. The connection is used to manage the lifecycle of the channels, a client have to check the statuses of the connections to be aware if a user action such as an authentication renewal is needed. See the dedicated 'HowTo' Update authentications for more information.

The statuses are defined at 2 levels:

  • At the connection level: It is a global status deduced from the statuses of its channels: SUCCESS, PARTIAL_SUCCESS, FAILED, RUNNING, CLOSED or NONE
  • For each channel, it allows you to
    • Follow the synchronization progress: NEVER, RUNNING, SUCCESS, PARTIAL_SUCCESS, FAILED, CLOSED, EMPTY
    • Get the error type: AUTH_FAILED, TOKEN_EXPIRED, PASSWORD_CHANGE_REQUIRED, CHALLENGE_REQUIRED, ...

You can have more information in the 'HowTo' Understanding Error Cases or get the status list in the reference documentation.

PSD2 and widget#

With PSD2, the notion of requisitioning user consent was introduced. Using OXLIN Widget, we automatically collect the user consent with a webview.

The widget allows to parametrize the way the channels are retrieved. You have the possibility to choose the channel definition you want to use when several channels are available for a provider or sequence the REDIRECT and EMBEDDED channel definitions without leaving widgets, allowing to recover all the data available for the user.

For exemple, for the create session endpoint, parameters are the following:

  • channel_definition_id: Parameter used to identify the target channel definition to edit.
  • multiple_channels (default false) Whether the partner wants to retrieve the payment accounts available in a PSD2 API (REDIRECT channel) then, the other accounts (credits, savings...) available in the web interface of the provider (EMBEDDED channel).
  • select_channel (default false): Whether the providers list widget displays a popup to choose the channel definition.
  • select_accounts (default false): Whether the widget displays a page that allows the user to choose which accounts to share with the partner

List available providers#

The provider represents a financial institution available in our aggregation platform.

The list of compatible providers is available on a dedicated endpoint. A provider contains information for the user to identify the service he is using, and for the integrator to authenticate the user using one of the available channel definitions.

The providers have different account type scopes on each channel identified by the account_types field and the related filter for the clients to be able to select the providers and perform the authentication needed by the functional domain of the data. Be careful in the implementation that the channel scopes will evolve when a provider launches or makes a new release of their API.

This resource is paginated and will return only 100 providers without any filter. Remember to manage pagination to list all the providers.

The reference documentation describes the providers API endpoint parameters.

curl -sk \
https://sandbox-api.oxlin.io/v2.1/providers?pagination=false \
-H 'authorization: Bearer ${client_access_token}'
# Response
HTTP/1.1 200 OK
[
# ...
{
"id":"119",
"name":"HSBC",
"branch_name":"",
"base_url":"https://www.hsbc.fr/1/2/hsbc-france/particuliers/connexion",
"logo_url": "https://static.oxlin.io/common/pictures/providers_logos/119.png",
"country_code":"FRA",
"channel_definitions":[{
"id":"redirect1",
"mode":"REDIRECT",
"account_types": [
"CHECKINGS","CREDIT_CARD"
],
"interactive": false
},{
"id":"embedded1",
"mode":"EMBEDDED",
"account_types": [
"SAVINGS","LOAN"
],
"credentials":[
{
"id":"3500",
"label":"Identifiant",
"regexp":"^[\\a-zA-Z0-9@._-]{7,}$",
"type":"TEXT",
"encrypt":false
},
{
"id":"3501",
"label":"Réponse mémorable",
"regexp":".+",
"type":"PWD",
"encrypt":false
},
{
"id":"3502",
"label":"Mot de passe (8 car. min.)",
"regexp":"^.{8,}$",
"type":"PWD",
"encrypt":true
}
]
}],
"unavailable":false
},
# ...
]

An integrator can use these results to build a provider list and make the user provide his access to the defined channels.

List the channels for a dedicated provider#

You can also get the channel(s) for a dedicated provider by calling the Oxlin API '/connections/{id}' endpoint allowing you to retrieve the information about a specific connection. The id of the returned provider is equal to the id in the path. Channels status report the results of last synchronization.

curl -sk \
https://sandbox-api.oxlin.io/v2.1/connections/87 \
-H 'authorization: Bearer ${client_access_token}'
# Response
HTTP/1.1 200 OK
[
{
"id": "29171",
"provider_id": "87",
"name": "Linxo Test Bank (5)",
"status": "PARTIAL_SUCCESS",
"creation_date": 1588869948,
"auto_sync": true,
"logo_url": "https://static.oxlin.io/common/pictures/providers_logos/87.png",
"channels": [
{
"channel_definition_id": "8701",
"mode": "REDIRECT",
"expires": 1596645948,
"status": "PARTIAL_SUCCESS",
"last_success_date": 1591416989,
"last_end_date": 1591416989,
"credentials": [],
"account_types": [
"CHECKINGS",
"CREDIT_CARD"
]
},
{
"channel_definition_id": "8700",
"mode": "EMBEDDED",
"status": "EMPTY",
"account_types": [
"SAVINGS",
"LOAN",
],
"eligible_accounts": false
}
],
"owner": {
"name": "M BULIA Maha"
},
"consent_per_account": false
}
]

Add a new channel with the widget#

The edit connection flow allows a user to edit an existing connection and also to update its credentials. The service will update the connection data in the database and try to reach the provider if the credentials are updated.

This widget also allows you to add a new channel definition when you want to add the different account types.

The client can provide some parameters to customize the screen flow and he is notified of the results by a callback URL.

Request examples:

# Add the channel tat handles payment accounts for the connection#85, aggregate asynchronously and select accounts
curl https://{widget_uri}/widget/edit_credentials?session_id=4242XXX&redirect_uri=https://mywebsite.coom/callback%26channel_definition_id=REDIRECT1%26provider_id=42%26connection_id=85%26captive_mode=true%26select_accounts=true

Response example:

# Success case, the user will be redirect on
{callback_uri}?result=edited&status=success&connection_id=42
# Expired case, the user will be redirect on
{callback_uri}?result=expired
# Cancelled case, the user will be redirect on
{callback_uri}?result=cancelled

Embedded to Redirect migration#

API v2.1 was introduced to handle PSD2 requirements. Consequently, REDIRECT channel definitions, responsible for interactions with PSD2 APIs will be enabled ASPSP by ASPSP (or set of ASPSPs by set of ASPSPs).

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. A new connection can only be created with an EMBEDDED channel. All the accounts will be linked to this channel.

With PSD2, REDIRECT channel definitions are enabled.

Process#

You have to follow the channels statuses so as to know if a PSD2 migration is performed.

A REDIRECT channel with a status equal to EMPTY indicates a new API channel is available.

In this case, you need to indicate your user he must connect to the bank site in order to enter his credentials. His check account will then be available from the REDIRECT channel instead of the EMBEDDED channel. It is effective when the status is not EMPTY anymore.

This channel contains also an eligible_accounts field (boolean) that can be used to know when the PSD2 migration is done.

This field is present in channels with EMPTY status only. With this field, an API client can easily know whether a user should add a channel to make sure all his accounts will keep being synchronized successfully in the future or if adding a channel is purely optional.

More in details, it has been added to allow API clients differentiating 2 cases:

1- REDIRECT channel should be added:

provider A
|_ channel definition EMBEDDED
account types: CHECKINGS, CREDIT_CARD, SAVINGS, LOAN
|_ channel definition REDIRECT
account types: CHECKINGS, CREDIT_CARD
connection
|_ channel definition EMBEDDED
accounts: 1 CHECKINGS, 1 SAVINGS
|_ channel definition REDIRECT
EMPTY

2- REDIRECT channel might be added:

provider A
|_ channel definition EMBEDDED
account types: CHECKINGS, CREDIT_CARD, SAVINGS, LOAN
|_ channel definition REDIRECT
account types: CHECKINGS, CREDIT_CARD
connection
|_ channel definition EMBEDDED
accounts: 1 SAVINGS
|_ channel definition REDIRECT
EMPTY

In use case 1), adding a REDIRECT channel is important to guarantee the CHECKINGS account will be synchronized successfully in the future.

=> eligible_accounts is true in the EMPTY REDIRECT channel

In use case 2), adding a REDIRECT channel is optional. The connection only has a SAVINGS account. There is no need to add a REDIRECT channel to keep synchronizing this SAVINGS account.

=> eligible_accounts is false in the EMPTY REDIRECT channel