Skip to main content

Creating connections

Flow details and paramaters​

Widget based integration

The widget proposes several parameters (reference documentation) that let you customize the widget according do your needs.

  • wait_sync_end : The widget waits until the end of synchronization before redirecting
  • redirect_url : Represents the page on your application where you want the user to be redirected when the widgets finish the process.
  • consent_per_account : If true, the widget displays account selection page after step 4. If expected_account_types = ALL and consent_per_account = true, the widget displays account selection page after 'REDIRECT' and 'EMBEDDED' flow.
  • expected_account_types :
    • ALL : The user can add his payment (checking or credit card) account using the PSD2 'REDIRECT' flow when this mode is supported by this bank and after he can add his loan and saving account(s) using the 'EMBEDDED' flow or all account type if mode: 'REDIRECT' is not supported by this bank.
    • PAYMENT : The user can add his payment (credit card or checkings) account(s)
    • OTHER : The user can add his loan and saving account(s) using the 'EMBEDDED' flow, in some cases depending on the bank support, payments accounts will be also connected to.
  • cancel_url : Represents the page on your application where you want the user to be redirected if he cancels the process.
  • congrats_bypass_delay : It is the waiting time displayed on success page before the user being redirected to redirect_url after synchronization. If congrats_bypass_delay = 0, the widget bypass success page.
  • provider_id : If not empty, the widget bypass bank selection page. The widget will take this provider for the rest of the flow
  • aspsp_callback_uri : Represents the page of your application (Iframe or mobile application) after the bank's website redirection. It's inevitable when using a 'REDIRECT' channel AND the widget is integrated within Iframe or mobile application. It must contain the URL which load the widgets.
  • auto_sync : Indicates whether this connection is automatically synced or not
  • countries : The widget displays only providers originating from the specified country.
  • locale : The widget is translated into french, english and italian languages.
  • favorite_providers : Providers set in this parameters are displayed at the top of the bank list in the widget.
  • If you have your own agreement, you can customize or bypass Terms and conditions.
    • Bypass : terms_body should be empty
    • Customization : fill this field with your information
      • terms_header
      • terms_body
  • display_provider_logos : When false, page is rendered without integrator logo.
  • display_integrator_logo : When false, page is rendered without archive option.
  • cancel_button_text :The widget displays this text in cancel button.
  • redirect_button_text : The widget displays this text in redirect button on success page.

The widget proposes other parameters to customize color, font… etc. You can read this documentation to lear more about the design customization.

Connections and channels​

Widget based integration

A connection is separated in 2 channels:

  • Redirect : Corresponds to the DSP2 API connection type for payment accounts (account type = Credit card or Checkings)
  • Embedded : Corresponds to the 'scraping' connection type to get access to saving, credit accounts and eventually payment accounts (account type = Credit card or Checkings) when the bank does not support the Redirect channel

For exemple, with the parameter expected_account_types :

  • ALL : The user can
    • add his payment (checking or credit card) account using the PSD2 'REDIRECT' flow when this mode supported by the bank.
    • and after he can add his loan and saving account using the 'EMBEDDED' flow or all account types if mode: 'REDIRECT' is not supported by this bank.
  • PAYMENT : The user can add his payment (credit card ot checkings) account(s)
  • OTHER : The user can add his loan and saving account(s) using the 'EMBEDDED' flow, in some cases depending on the bank support, payments accounts will be also connected to.

Add channel on existing connection​

The edit credential flow allows a user to edit an existing connection and also to update its credentials. The service will update the connection data in the database and try to reach the provider if the credentials are updated.

This widget also allows you to add a new channel when you want to add the different account types.

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

Request example:

# Add the channel that handles payment accounts for the connection#85, select accounts 
curl https://{widget_uri}/v2.1/widget/edit_credentials?session_id=4242XXX&redirect_url=https://mywebsite.coom/callback&expected_account_types=PAYMENT&provider_id=42&connection_id=85

Response example:

# Success case, the user will be redirect on
{callback_uri}?result=edited&status=success&connection_id=42

# Expired case, the user will be redirect on
{callback_uri}?result=expired

# Cancelled case, the user will be redirect on
{callback_uri}?result=cancelled

Migrations DSP2​

API v2.1 was introduced to handle PSD2 requirements. Consequently, 'REDIRECT' channel, responsible for interactions with PSD2 APIs will be enabled ASPSP by ASPSP (or set of ASPSPs by set of ASPSPs).

Initially, a provider has only an 'EMBEDDED' channel. This channel definition covers all the account types our API currently supports: CHECKINGS, CREDIT_CARD, SAVINGS, LOAN. A new connection can only be created with an 'EMBEDDED' channel. All the accounts will be linked to this channel.

With PSD2, 'REDIRECT' channel are enabled.

Process

You have to follow the channels statuses to know if a PSD2 migration can be performed.

A 'REDIRECT' channel with a status equal to EMPTY indicates a new API channel is available.

In this case, you need to indicate your user he must connect to the bank site in order to enter his credentials. His check account will then be available from the REDIRECT channel instead of the EMBEDDED channel. It is effective when the status is not EMPTY anymore.

This channel contains also an eligible_accounts field (boolean) that can be used to know when the PSD2 migration is done.

This field is present in channels with EMPTY status only. With this field, an API client can easily know whether a user should add a channel to make sure all his accounts will keep being synchronized successfully in the future or if adding a channel is purely optional.

More in details, it has been added to allow API clients differentiating 2 cases:

1- REDIRECT channel should be added:

provider A
|_ channel definition EMBEDDED
   account types: CHECKINGS, CREDIT_CARD, SAVINGS, LOAN
|_ channel definition REDIRECT
   account types: CHECKINGS, CREDIT_CARD

connection
|_ channel definition EMBEDDED
   accounts: 1 CHECKINGS, 1 SAVINGS
|_ channel definition REDIRECT
   EMPTY

2- REDIRECT channel might be added:

provider A
|_ channel definition EMBEDDED
   account types: CHECKINGS, CREDIT_CARD, SAVINGS, LOAN
|_ channel definition REDIRECT
   account types: CHECKINGS, CREDIT_CARD

connection
|_ channel definition EMBEDDED
   accounts: 1 SAVINGS
|_ channel definition REDIRECT
   EMPTY

In use case 1), adding a REDIRECT channel is important to guarantee the CHECKINGS account will be synchronized successfully in the future.

=> eligible_accounts is true in the EMPTY REDIRECT channel

In use case 2), adding a REDIRECT channel is optional. The connection only has a SAVINGS account. There is no need to add a REDIRECT channel to keep synchronizing this SAVINGS account.

=> eligible_accounts is false in the EMPTY REDIRECT channel