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
andEMBEDDED
channels are available for a given bank, the user will follow theREDIRECT
flow first, and then, in a second step, be asked to follow theEMBEDDED
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
- To bypass the screen: provider the
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