Skip to main content

Use the widget

Presentation#

The widget allows to delegate some tasks. After having requested a session, user is redirected to a browser to lead them in wanted fonction. A return URL transmits process result and necessary information. Events are tracked to follow user behavior.

Widget based integration

The widget entry points are the following:

  • Create a session: authentification to be able to use the widget (POST /widget_session)
  • Add a connection: add a connection to a provider by filling a credential form (GET /widget/add_connection)
  • Edit credentials: edit an existing connection and optionally update its credentials (GET /widget/edit_credentials)
  • User Input: build the form making it possible to enter challenges (GET /widget/user_input)
  • Accept terms and conditions: for a given end user, approve the service Terms and conditions' current version (GET /widget/terms)
  • Professional account: provide information regarding any professional account (GET /widget/professional-account)
  • Manage accounts (PSD2 mandatory): to modify the list of accounts in a connection (GET /widget/manage_accounts)

The widget is able to handle web redirects and multiple authentication management, using our API.

To select a bank or a test bank, you need to add a connection to a provider.

You can therefore redirect the user on the widget with the link provided by the response of the widget session (in the '_links' field), or by building it by concatenation of this endpoint with the session_id. The following actions are performed:

  • It will allow you to display a form to select the bank and will try to reach this provider after filling in a credential form.
  • The provider is connected
  • The account list retrieved
  • You accept PSD2 consent (all existing and future bank accounts for Oxlin consent)
  • The synchronisation is started.
  • If captive_mode parameter is enabled, The user will remain on the widgets until the last bank operation is retrieved.

The connection is used to manage the lifecycle of the channels. Using the PSD2 redirect channel, the connection is created as the user is redirected back to our services and we provide a ready to use connection when your user comes back on the URI you provided.

Depending on the widget options you choose, you may need to implement a waiting step before the data is collected in our systems.

The widget integration#

Terms and conditions#

When you create a user, he must validate the OXLIN terms and conditions. If he does not, all API calls will return 401 errors indicating that the user has an action to perform.

Oxlin is a payment establishment, approved by the ACPR for account information and payment initiation services.

OXLIN widgets detect when the user must accept the terms and conditions. When the user uses a widget, it is first redirected to the UI allowing to accept Oxlin terms and conditions and authorize your user to transfer their account data to you.

PSD2 channels#

Banks' PSD2 APIs allow the user authentication by obtaining his credentials, in order to access data for checkings and credit card accounts only. When a connection is added, the widget allows the user to be redirected to the bank's access portal which is responsible of his authentication.

These credentials expires after 90 days. In this case, the widget

  • either manage the update of its credentials thanks to a user interface thanks to the edit_credentials endpoint.
  • or allows to retrieve the redirect URL that is produced by calling the endpoint POST /providers/<provider_id>/channel_definitions/<channel_definition_id>/authorize_url in the redirect channel definition. The URL will contain the information necessary to handle security tokens negotiation after the authentication. You can therefore redirect your user to the provider's authentication website.

According to the PSD2, the user will need to perform a multifactor authentication (MFA) with an SMS or a security device when he adds a new connection and when he renews its credentials.

Notice that to cover the entire functional scope of your application, you may still need to use the form based credentials (scraping mode) to collect the data not available via PSD2 API.

Consent requisition#

When you use the OXLIN PSD2 agreement, with the OXLIN consent, the user agrees to share all existing and future bank accounts related to their credentials.

When a new account is available on the connection, it is automatically added to the user's connection without the need for re-consent.

Internationalization#

Widgets are, for now, translated into french and english languages. Widgets are able to rely on your browser default language to switch to it if available. The default supported language is french. It is possible to specify a language by setting a lng query parameter when requesting a widget. Example: https://embed.oxlin.com/widget/add_connection?lng=en will force the english version of the widget.

Available languages:

NameValue
Englishen
Frenchfr

Requirements to use OXLIN widgets#

Widget session sequence diagramm

The Widget service provides an endpoint to create a session from the user credentials. It will create a session containing the credentials and return the session ID.

## Connection flow with the widget

Widget flow

Actors :

  • Auth Server: The delegated authentication server.
  • Webview Service: The service that hosts the webviews and connects to the API.
  • User: the end user of the client
  • Client: the service company that uses our services as aggregation provider
  • API: The existing REST API v2

The main features:

  • You create a session (widget) (quickstart)

    The widgets need a valid user access token and optionally a refresh token. If you do not provide a refresh_token while creating a new session, widget service won't be able to refresh the access_token for you. As a consequence the lifetime of the session will be linked to the lifetime of the provided access_token.

  • You **add connection (widget) quickstart These widgets require an active session, the Webview service will immediately redirect to the redirect_uri with an "expired" result if the session has expired. The client can provide some parameters to customize the screen flow and he is notified of the results by a callback URL.

    • A credential form is displayed to your user

    • The provider is connected

    • The account list retrieved

    • You accept PSD2 consent (all existing and future bank accounts for Oxlin consent)

    • The synchronisation is started.

    • If captive_mode parameter is enabled, The user will remain on the widgets until the last bank operation is retrieved.

      When you create the session, you have the option to provide the parameters "provider_id", "channel_definition_id", "captive_mode", "select_accounts", "multiple_channels", "select_channel". When they are provided as query string parameters in add connection widget, they overwrite those recorded in the session.

And, if needed:

  • You may [edit credentials (widget)](/reference-accounts-api/#tag/manage-widget/paths/~1widget~1edit_credentials/get)

    • Modify a widget parameter
    • Update the user credentials
    • Add a new channel

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

    These screens require an active Webview service session, the Webview service will immediately redirect to the redirect_uri with a result of "expired" if the session is expired.

  • You may enter new challengeswith User input (widget)](/reference-accounts-api/#tag/manage-widget/paths/~1widget~1user_input/get) This widget allows you to build the form making it possible to enter challenges. You need to use queue polling.

    The results are added as query string parameters to the redirection URL provided when creating a session or displaying the widget

  • Your end user can validate the processing of professional accounts with [Professional account (widget)](/reference-accounts-api/#tag/manage-widget/paths/~1widget~1professional-account/get)

  • Your end user can [Accept terms and conditions (widget)](/reference-accounts-api/#tag/manage-widget/paths/~1widget~1terms/get)

    Once "Terms and conditions" are validated, the webview service will automatically redirect to a provided redirect_uri with a "success" or "error" result.

  • You may modify the list of accounts in a connection if you have a PSD2 approval with [Manage accounts (widget)](/reference-accounts-api/#tag/manage-widget/paths/~1widget~1manage_accounts/get)

    This widget allows you to modify the list of accounts in a connection by consenting to the addition of new accounts or by stopping consent for certain accounts. A synchronization is triggered for consented accounts.

## The webviews

The Webviews provide a user interface allowing user to interact easily with the banking requests

  • Bank adding
  • Identifiers updating
  • Strong authentication
  • Oxlin terms and conditions validation
  • Professionnal accounts management

The flows are created from the combination of several parameters :

The flows are created from the combination of several parameters :

ParameterValueDefaultDescription
captive_modeBooleantrueWhen this parameter is set to false (default value), we try to keep the user as short as possible on widgets. This implies that you are responsible for polling the event queue to retrieve the account list or transactions. We just validate that the user IDs are valid and functional. When this parameter is set to true, the screens are linked synchronously. The user will remain on the widgets until the last bank operation is retrieved. This greatly simplifies the integration work.
select_accountsBooleanfalseWhen this parameter is set to false (default value), we get the list of all accounts available for the provider's channel definition. When this setting is set to true, we display a list of accounts, allowing your user to share only the data they want to aggregate via widgets. You must have a PSD agreement to use this parameter
multiple_channelsBooleanfalseWhen the provider has two different channels to retrieve payment account information and information from other types of accounts, we prioritize first the REDIRECT channel and then the EMBEDDED channel. When this parameter is false and the provider has several channels, we only realize the first one. When this parameter is true, we aggregate all channels through webviews.
select_channelBooleanfalseWhen the provider has two different channels to retrieve payment account information and information from other types of accounts, we prioritize first the REDIRECT channel and then the EMBEDDED channel. When this parameter is false and the provider has several channels, we choose the REDIRECT channel definition. Most of the time this channel is dedicated to the recovery of payment accounts. When this paramater is set to true and the provider has several channels, a popup appears and asks the user if he wants to add payment accounts (REDIRECT channel definition) or savings accounts (EMBEDDED channel definition).

When an operation takes more than a few seconds, a loading screen may appear. Actions that take a little time are usually those related to the captive_mode parameter. When this parameter is set to true, we wait for all the necessary information from the current step to be gathered before proceeding to the next step.

Exemples:

  • When the REDIRECT channel is selected:

    • The user selects his provider from the list of available providers.
    • The REDIRECT channel is selected. The user is informed that by connecting to the website of his provider, he agrees to transfer the information to you through OXLIN
    • The user is redirected to the provider's site, authenticates himself following the provider's screens. The user consents, by connecting to the provider's website, he authorizes OXLIN to send you banking information.
    • The provider redirects to the widgets, we create the connections and we give you back your hand after a few seconds.
  • When the EMBEDDED channel is selected

    • The user selects his provider from the list of available providers.
    • The EMBEDDED channel is selected.
    • The user fills his credentials
    • We validate the credentials, create the connection and we give you back the hand after few seconds.
  • (Declination) Skip provider list

    • You force the provider with the parameter **provider_id**, so the providers list widget is not displayed
    • OXLIN prioritizes channel definitions (in this example, REDIRECT channel is available)
    • The user fills his credentials
    • We validate the credentials, create the connection and we give you back the hand after few seconds.

      If the value provided for provider_id property is not valid, the user will be redirected on your **redirect_uri** with an error message.

  • (Declination) Skip provider list & force the channel definition

    • You force the provider with the parameter **provider_id**, so the providers list widget is not displayed

    • You force the channel with the parameter **channel_definition_id** (EMBEDDED1)

    • The user fills his credentials

    • We validate the credentials, create the connection and we give you back the hand after few seconds.

      If the values provided for provider_id & channel_definition_id properties are not valid, the user will be redirected on your redirect_uri with an error message.

  • (Declination) Let the user choose the channel definition

    • The user selects his provider from the list of available providers.
    • The provider has several channel definition, we ask to the user which channel he wants to use: parameter **select_channel** set to true
    • Depending on the channel definition chosen, the user will continue on the screens dedicated to the REDIRECT or EMBEDDED path
  • (Declination) Use all channels during the aggregation

    • The user selects his provider from the list of available providers.
    • OXLIN prioritizes channel definitions: parameter **multiple_channels** set to true
    • The user fills his credentials
    • We validate the credentials, create the connection
    • Then we invite the user to edit his connection to add the second channel
  • (Declination) Use all channels and select accounts

    • The user selects his provider from the list of available providers.
    • OXLIN prioritizes channel definitions: parameter **multiple_channels** set to true
    • The user fills his credentials
    • We validate the credentials, create the connection
    • The list of available accounts is displayed and the user can choose which data he wants to aggregate: parameter **select_channel** set to true
    • Then we invite the user to edit his connection to add the second channel
    • The list of available accounts is displayed and the user can choose which data he wants to aggregate.

Request a refresh access token#

A token and a refresh token are returned when you authenticate the client.

Access tokens have limited lifetimes. If your application needs access to the API beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens.

The widgets need a valid user access token and optionally a refresh token to manage the Connect Authentication of the user with the API. The access token and the refresh token are provided in the response of the user authentication

If you do not provide a refresh_token while creating a new widget session, widget service won't be able to refresh the access_token for you. As a consequence the lifetime of the session will be linked to the lifetime of the provided access_token.

You can have detailed information about authentication in the dedicated chapter of the Advanced API integration page.

Request example:

curl -s -X POST https://sandbox-auth.oxlin.io/token -d refresh_token=${refresh_token_value} -d grant_type=refresh_token -d redirect_uri=${redirect_uri} -d client_id=${client_id} -d client_secret=${client_secret} -H 'Accept: application/json' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8'

Response example:

{
"access_token": "eyJhbGciOiJSUzI1NiJ9 ... mBy308Znno7AWuaGNoyoRgwSuYwdo",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "3495142fgte56fb3f13b",
"id_token": "eyJhbGciOiJSUzI1NiJ9 ... 9d016f0e2.350a2157fa75b9bd4c166340"
}