Custom connection implementation
Last updated
Last updated
Building a full custom implementation of the connection protocol is only available to integrators holding the Agent Status as defined in article L523-1 of Code Monétaire et Financier (CMF). Please validate the integration with your account manager before proceeding. This option requires a significant amount of work and testing. We advise to rely on our unless necessary.
The following diagram illustrates the general recommended UX for adding a connection, see below for the detail of the different steps:
For technical and regulatory reasons, bank connectors require a richer UX with multiple authentication steps as soon as your use-case involves gathering multiple account types (payment and non-payment). We recommend to present these steps sequentially and to follow these best practices:
If your use case can work with a partial list of the user accounts, we recommend to present the aggregation of additional account types as an option on the activation screen:
If your use-case only requires either payment or non-payment accounts, you should limit the connection flow to only the required account types:
If you always need to get all accounts for a given user (payment and non-payment accounts), chain the authentication steps:
The full protocol of connection addition involves the following steps:
obtain a user context by creating a temporary user resource, or using an existing token;
if applicable, let the user select the target connector, and optionally the specific connector source (bank connectors only);
follow the appropriate authentication mechanism for the selected connector or source, either redirecting the user to a third-party webview, or presenting to the user a form with a set of credentials fields;
handle connection creation with potential multiple steps (e.g. multifactor authentication);
get user consent and activate individual access to bank accounts and subscriptions;
for bank connections, repeat these steps for all available connector sources.
Connection addition is performed in the context of an authenticated user in our API. You must obtain a user-scoped access token to interact with our API.
For a new user, you can create a new access token in the API using the dedicated /auth/init endpoint:
Once obtained, this access token represents the newly created user. You have to store it and reuse it to subsequently add new connections to this user or query the associated data.
If applicable for your use case, you may present to the user a list of supported connectors to pick from. You can obtain the list from the /connectors endpoint:
As we may add or modify connectors frequently, we do not recommend using a static cache of connectors. Instead, always get the current available list when adding a new connection. You can manage the connectors available on your domain in the administration console.
You can filter the connectors list according to your needs, e.g. rely on the supported capabilities.
For bank connectors, we provide a mechanism to aggregate subsets of a user bank accounts through the addition of connector sources. Connectors providing both payment and non-payment accounts will usually present two or more sources. You can access the sources of a connector and their properties by expanding the previous call:
Adding sources to a connection separately and sequentially is required when integrating banking connectors. Failing to specify a source when adding a connection to a connector will result in a single source being available, hence with partial access to the end-accounts. Depending on your use-case, you can filter the sources to add using the account_types and capabilities attribute.
Make sure the disabled property of a source is null before interacting with it (sources can be (de)activated in your administration console). Also, the priority order of sources must be honored when adding them sequentially: add the source with the lowest priority value first.
Once a source has been added, you usually give the user the choice of selecting the accounts to synchronize or adding further accounts for the chosen connector. It is also possible to not let them add another source right away, or at all. For example, if you are only interested in payment accounts, we strongly recommend that you only offer to add the only source that provides these account types.
The required flow varies depending on the auth_mechanism of the selected connector or source.
The credentials mechanism involves presenting a form with a set of fields and posting the values to the API to create the connection.
If you are adding a single source to the connector, you should filter out the fields that do not match the name of the source. When adding a secondary source in a sequential experience, you should also filter out fields that are associated with sources already added, as the value is not required.
You should build and present a UI that handles all the possible configurations of form fields. We recommend that you present the label and description texts with the input control, and that you pre-validate the input using the required and regex properties.
All the field values must be end-to-end encrypted when sent to the API.
Connections or sources created with invalid credentials (refused by the establishment) are deleted at once. A new connection has to be created in that case when re-validating the form. Make sure you also handle the wrongpass error code that can be raised on posting the credentials.
The webauth mechanism involves delegating the authorization to a webview that should be presented to the end-user in a browser.
First, as with the credentials mechanism, determine the fields that you must present for the chosen connector. Check for any field whose auth_mechanisms include webauth:
When adding a secondary source in a sequential experience, you should filter out fields that are associated with sources already added, as the value is not required.
In the case there were presented fields, submit their values along with these parameters.
The redirect_uri that you provide here is required to match the configuration set in the administration console.
After authorization has been granted by the user in the webview, you will be redirected to the provided redirect_uri, with additional parameters added in the query:
Immediately after the connection or source is created, we may need additional information or an SCA to perform the first synchronization of the connection. According to the state of the connection or the source (either obtained in the API response or as a parameter of the redirect URI), you must take the steps described in the guide dedicated to connection state handling.
After a new connection or source is added and synced, new bank accounts and subscriptions are discovered and made available in the API.
However, due to GDPR enforcement, full synchronization is not enabled on these resources as an explicit and dedicated end-user approval is required. By default, they are flagged with the disabled property.
You can also use the expand=all_accounts,all_subscriptions feature on a connection to get the activable resources at once.
Once desired sources have been added, and the user has selected the appropriate accounts/subscriptions, you can active the accounts/subscriptions to enable the synchronization of their transactions and documents:
The UI to activate bank accounts or subscriptions is the recommended place to perform sequential addition of optional sources. First, let the user add the first source only using the above steps. Then, on listing the available accounts, you can propose an option to add more accounts by adding the next source if available (enabling accounts must be done in one call after the addition of the sources):
First, that you must present to the user. You can obtain them by expanding the list of connectors call above (?expand=fields), or perform a dedicated call:
When the user validates the form, send the chosen connector ID (optionally with the source) and the field values to the :
The above call will result in the creation of a new connection, returned in the response. As credentials are synchronously checked during this step, handle the HTTP connection appropriately to avoid timeouts. When adding additional sources to an existing connection, use the same request on the .
Once the user validates the form if any, linked to your token to secure the connection addition:
Then, open the in a browser and specify the connector ID and source:
You may / and prompt the end-user for activating them:
If you created a temporary user on initializing the process, you must eventually to a permanent access token. You may store this new token to access data of the user:
