Migrating to latest widgets

New widgets have been released, they are already documented here

Note our previous widgets are still documented in the same section, but they are marked as deprecated.

The migration process to our latests widget is detailled here under

Flow changes

There are two main changes regarding flows.

• In our new widgets, if both the REDIRECT and EMBEDDED channels are available for a given bank, the user will follow the REDIRECT flow first, and then, in a second step, be asked to follow the EMBEDDED flow. The second step is optional and an automatic redirection occurs after a few seconds.
• There is no longer an endpoint to accept terms and conditions. In other words, the /terms endpoint no longer exists. Instead, after choosing the bank, the user reaches a screen where he consents and accepts terms and conditions. This screen is displayed every time the user adds a connection or re-authenticates
• for an existing connection. You can customise or even skip this screen if you have your own licence. To do so, use the following parameters:
  • To bypass the screen: provider the terms_body parameter with an empty value
  • To customise the screen, you can use these two parameters:
    • terms_header
    • terms_body

Parameters changes

Endpoint updates

All the widgets endpoints are now available under the v2.1 version, which is part of the path:

• POST /v2.1/widget_session
• GET /v2.1/widget/add_connection
• GET /v2.1/widget/edit_credentials
• GET /v2.1/widget/user_input
• GET /v2.1/widget/manage_accounts

In sandbox, the full paths are:

• https://sandbox-api.oxlin.io/v2.1/widget_session
• https://sandbox-api.oxlin.io/v2.1/widget/add_connection
• https://sandbox-api.oxlin.io/v2.1/widget/edit_credentials
• https://sandbox-api.oxlin.io/v2.1/widget/user_input
• https://sandbox-api.oxlin.io/v2.1/widget/manage_accounts

Parameter updates

Endpoint POST /v2.1/widget_session

There are now only 4 parameters for this endpoint:

• access_token
• refresh_token
• client_id
• client_secret

Their role and behaviour did not change compared to our previous widgets.

Note all the functional parameters have now to be provided only to other endpoints.

Parameter changes

The following changes are related to endpoints:

• GET /v2.1/widget/add_connection
• GET /v2.1/widget/edit_credential
• GET /v2.1/widget/user_input
• GET /v2.1/widget/manage accounts

name in previous widgets	name in new widgets	comments
captive_mode	wait_sync_end	no functional change
redirect_uri	redirect_url	no functional change
select_accounts	consent_per_account	no functional change
channel_definition_id / multiple_channels	expected_account_types	see details below

In our previous widgets, you could use the channel_definition_id parameter to target a specific channel (which had a mode EMBEDDED or REDIRECT). You could also use the multiple_channels parameter to retrieve the payment accounts available in a PSD2 API first, and then, the other accounts (savings, loans) available in the web interface of the provider.

In our new widgets, the expected_account_types parameter replaces these two parameters. There are 3 possible values:

• ALL : the user can add his payment accounts (credit cards and checking accounts) first, and will then be asked to add his loans and savings accounts.
• PAYMENT : the user can add his credit card and checking accounts only
• OTHER : the user can add his loans and savings accounts only

As an API client, you just have to specify the account types you want to synchronise and our new widgets will choose the right flow for you.

Note the expected_account_types parameter is not available on the /v2.1/edit_credentials endpoint (since this parameter does not make sense for this endpoint).

New parameters

parameter	comments
cancel_url	URL the user will be redirected to if he cancels the process. If the cancel_url is not provided, no cancel button is displayed.
congrats_bypass_delay	It is the waiting time before the user is redirected to the success page (redirect_url) at the end of the process.Default: 5s
countries	The widgets display only the providers of the given countries.
locale	Our new widgets are available in French, English and Italian. By default, the widget takes language of the browser. This parameter is used to force the language.
favorite_providers	The widget display the given list of providers at the top of the screen.

Customisation

Our new widgets offer the possibility to customise several parameters. You can read this documentation to lear more about the design customization.

Iframe or mobile application

If you integrate our new widgets in Iframes or in a mobile application, you can read this guide