Skip to main content

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

Widget based integration

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:

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 widgetsname in new widgetscomments
captive_modewait_sync_endno functional change
redirect_uriredirect_urlno functional change
select_accountsconsent_per_accountno functional change
channel_definition_id / multiple_channelsexpected_account_typessee 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

cancel_urlURL 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_delayIt is the waiting time before the user is redirected to the success page (redirect_url) at the end of the process.Default: 5s
countriesThe widgets display only the providers of the given countries.
localeOur 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_providersThe widget display the given list of providers at the top of the screen.


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