Custom connection implementation
UX guidelines
The following diagram illustrates the general recommended UX for adding a connection, see below for the detail of the different steps:
Bank and Wealth implementation
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:
Option 1: Present additional accounts as an option (recommended)
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:
Option 2: Restrict aggregation to required accounts only
If your use-case only requires either payment or non-payment accounts, you should limit the connection flow to only the required account types:
Option 3: Force chaining of authentication flows
If you always need to get all accounts for a given user (payment and non-payment accounts), chain the authentication steps:
Technical 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.
User context
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.
Connector selection
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.
Source refinement
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.
Add the connection or source
The required flow varies depending on the auth_mechanism of the selected connector or source.
Credentials connector/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.
Webauth connector/source
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:
Resume connection state
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.
Activate bank accounts and subscriptions
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):
Persist the created user
Last updated
