Skip to main content

Using the API

How to use this documentation#

This documentation is organized in five different parts allowing you to gradually increase your skills:

  • A quick start guide allowing you to easily set up a basic but functional service,
  • An API introduction describing the context, the main concepts, the components, and the environment,
  • Some How to explaining how to set up the main functionalities with exemples,
  • An advanced guide describing the Oxlin API in a more technical way,
  • A reference documentation to have detailed information about all the API endpoints.

A quick presentation#

The Oxlin 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 Oxlin 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 banking based 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 scraping of 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. Oxlin APIs are 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 Oxlin 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 API or the client API to perform operations on your users.
  • Fully PSD2 and GDPR compliant for payment initiation and account aggregation.

Some key definitions#

The Roles#

  • 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.

The Security#

Overview#

When using the OXLIN 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 the basic client credential flow.

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).

The Widget#

OXLIN widgets allow a quick integration of the OXLIN aggregation solution. Thanks to a responsive UI with several webviews displayed according to the context, you can easily integrate this solution into your ecosystem. OXLIN widgets are compatible with PSD2 banking APIs.

When you do not have PSD2 agreement, you are required to perform all aggregation via OXLIN widgets and the end user has to validate OXLIN 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, ...

OXLIN 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: REDIRECT mode,
  • Display a form to accept the PSD2 consent in REDIRECT mode,
  • 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: EMBEDDED mode),
  • 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 resources#

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 Oxlin API allows to retrieve user accounts and transactions from different providers defined with two non-exclusive channels.

resources

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:
    • REDIRECT indicating that the user should be redirected on a web browser to perform an authentication on the provider's website (using the PSD2 directives)
    • EMBEDDED indicating 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, Oxlin 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.

The events#

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.

Practical aspects#

Environment#

When you use the OXLIN 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 OXLIN widgets with the same components as the production ones. Go to the reference documentation for more information

The Linxo test bank#

The 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.

Next steps#

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 reference documentation allows you to find specific information on API endpoints for more advanced needs