Using the API
How to use this documentation
This documentation is organized in five different parts allowing you to gradually increase your skills:
quick start guideallowing you to easily set up a basic but functional service,
API introductiondescribing the context, the main concepts, the components, and the environment,
How toexplaining how to set up the main functionalities with exemples,
advanced guidedescribing the Accounts API in a more technical way,
referencedocumentation to have detailed information about all the API endpoints.
A quick presentation
The Accounts API
On 13th January 2018, the Payment Services Directive 2 (PSD2) came into full effect in 22 European countries, including France. This has opened the door to open banking by allowing the use of open APIs to enable apps to access bank data. As part of PSD2, third-party providers are allowed regulated access to customer accounts. This is facilitated by two services, Account Information Services (AIS) and Payment Initiation Services (PIS).
The Accounts API is used to link a third-party application to the banking application for Account Information Services (AIS). The regulations require banks to provide secure access to their customers' data, with their consent, of course, to authorized service providers.
Only PAYMENT accounts are covered by the PSD2. As a consequence, data acquisition is carried out in two ways:
Open bankingbased on banks APIs. To meet the requirements of PSD2, banking institutions will have to adapt their online interface or offer a specific interface (API) that will allow communication with the third-party application. Only payments accounts can be retrieved.
Screen scrapingof data (access to customer accounts via their identifiers) for all the accounts not covered by PSD2 and/or payment accounts if PSD2 is not available.
The main features
- Platform as a service with a dedicated or mutualized environnement. Accounts API is a full REST API and can be integrated into a web site or a native application.
- Security state of the art based on ISO 27001 certification. Once the user agreed to transfer his data to you via the Linxo Connect platform, you have fully secured access to all the data we can provide.
- Easy to integrate with widgets, handling complexity for you, on your application or on your website, for creation of bank connections or edition of bank identifiers.
- Manage all payments, credit and savings accounts with a unique API. You can use the
user APIor the
client APIto perform operations on your users.
- Fully PSD2 and GDPR compliant for payment initiation and account aggregation.
Some key definitions
- The Client (The Third-Party Application): the service company that uses our services as aggregation provider. It is the application that is attempting to get access to the user's account. It needs to get permission from the user before it can do so.
- The User (Resource Owner): The resource owner is the person who is giving access to some portion of their account.
- The Authorization Server: The delegated authentication server. This is the server that allows to authenticate both your client and the user account
- The Widget: The service that hosts the webviews and connects to the API.
- The API (Resource Server): The resource server is the API server (REST API v2) used to access the user's information.
- The provider: The user's financial institution.
When using the Accounts API, you need to authenticate both the client (you) and the user account from which you would like to retrieve information. To do so, you will need to negotiate an OAuth2 access token with our Authorization server.
Client and user authentication
You have to identify yourself to recover your users' data in two different ways:
- A user authentication to manage this user's data. It is set up according to the 'Ressource owner password credential' flow. It is also needed to create a widget session. We recommend a password based on 6 characters minimum with at least one letter and one number.
- A client authentication allowing you to manage your users and their data. It is set up according to
basic client credentialflow.
If you have the corresponding rights assigned to your 'client' role, you may manage your users directly and use your client access to get the resources of all your users ('client' mode).
Linxo Connect widgets allow a quick integration of the Linxo Connect aggregation solution. Thanks to a responsive UI with several webviews displayed according to the context, you can easily integrate this solution into your ecosystem. Linxo Connect widgets are compatible with PSD2 banking APIs.
When you do not have PSD2 agreement, you are required to perform all aggregation via Linxo Connect widgets and the end user has to validate Linxo Connect terms and conditions.
The widget allows you to recover all of your user accounts from one or several banks via PSD2 APIs and/or scraping. It can be configured to help you meet your needs: redirection, provider selection, data types to retrieve, captive mode, channel selection, ...
Linxo Connect widget allows you to:
- Redirect the user to the terms and conditions acceptance web page,
- Display a web interface to select one or more financial institutions,
- For PSD2 APIs, redirect the user to the bank authentication web page for checkings and credit card accounts:
- Display a form to accept the PSD2 consent in
- Collect data not available via PSD2 API: redirect the user to a credentials form to establish a secure
connection on the bank's site, using scraping:
- Edit credentials when they change (user modification or bank renewal),
- Listen the events to be able to set up the necessary actions,
- Create and synchronize the connection for each bank and for all accounts (PSD2 or not),
- Manage the user access token refresh
the Quicktart allows you to be guided in the use of the widget but you can also find more detailed information in the advanced use chapter or in the reference guide for the entrypoints description.
The user is at the center of the API resources. it will be used to group connections of banking providers and store the accounts and transactions.
The Accounts API allows to retrieve user accounts and transactions from different providers defined with two non-exclusive channels.
The data structure is the following:
- User: Owner of connections, accounts and transactions
- Provider: Institution containing the user's data on which we are able to create a connection to retrieve the information
- Connection: Connection to the Provider
- Channel: The channels represent the links between our service and the provider.
The connection type is defined with two non-exclusive channels:
REDIRECTindicating that the user should be redirected on a web browser to perform an authentication on the provider's website (using the PSD2 directives)
EMBEDDEDindicating that a form to collect users credentials is built (scraping mode).
- Account: User's account for a provider
- Transaction: Banking transaction
- Category: Category for a Transaction
Accounts and transactions retrieval
New bank adding causes first synchronization. By default, Linxo Connect performs a synchronization daily but it can also be performed on demand through the API.
Linxo synchronizes each connection by using identifiers recorded in connections, to connect to the bank to recover new user data: balance, transaction list, detection of new bank accounts and financial products. Connection contains date of last synchronization. Synchronization could require a user action (strong authentication, bank’s form validation).
We can follow the synchronisation progress with queues or webhooks. When a synchronization occured, events are generated and you can retrieve them by subscribing to a queue and polling it.
Events are generated in order to be able to follow the evolution of the various asynchronous processes. These events will contain several pieces of information like statuses which allow the client to be aware of various actions to be taken.
There are 3 different mechanisms allowing to follow the evolution of the actions in progress:
- Queues: The queue contains the list of events that occur during asynchronous processes (add a connection, synchronization of datas). For example, a client needs to listen to the synchronization events to be aware of the accounts availibility, if a challenged is required, or when a consent is provided by the user. You just have to subscribe to a queue to be able to receive these events.
- Events via the use of postMessage: if the service is meant to be used through iframes or popups, working with redirect_uri parameter cannot be a solution to retrieve results and statuses. PostMessage is a solution allowing the parent window of an Html iframe element to be aware of the flow's result.
- Webhook: Mechanism allowing an integrator to be notified of some business events sent on a URL communicated by the integrator. For example, when you do not know when the synchronization will take place, the event retrieved by the webhook will make you aware of it.
When you use the Linxo Connect solution, we provide you with two environments: a production and a sandox.
The sandbox is an environment dedicated to testing our solution, you can develop your solution and integrate Linxo Connect widgets with the same components as the production ones. Go to the reference documentation for more information
The Linxo test bank
Linxo test bank emulates the behavior of a real world provider. A configuration file makes it
possible to configure this bank and to supply it with different types of accounts and transactions.
This is useful to test your implementation.
A default file is available but you can implement your own file in order to be able to test a specific need.
Go to the the Linxo Test Bank 'HowTo' exemple or the reference documentation for more information.
Setting up the service with the widget is rather straightforward. The Quick Start page shows you how to do this. It allows you to create your users, define and set up a functional environment. The widget can be configured according to your needs.
The 'howTo' pages explain you the main use cases:
- the Linxo Test Bank
- Using queues and events,
- update authentications for user credential, strong authentication, refresh an access token,
- Working with providers and channels including Embedded to Redirect migration,
- Managing users and accounts,
- on demand synchronization,
- integrate widget using iFrame and events,
- Using webhooks,
- Disabling captive mode,
- Understanding Errors,
- Understanding credit cards, and finally,
- A checklist for a successful API integration
The reference documentation allows you to find specific information on API endpoints for more advanced needs