SCA & connection states

Connection synchronization

Retrieving user data from the connectors happens in an asynchronous way. Synchronization of a connection is performed:

  • right after the connection is created, or has its credentials updated;

  • automatically at regular intervals;

  • optionally on an explicit API request.

In either case, the sync process will upgrade the available dataset of the user if everything goes smoothly. But the process can also fail in various situations:

  • the website or the API of the target connector is unavailable;

  • the user needs to renew his consent or grant a supplementary explicit access for the synchronization to proceed (e.g. strong customer authentication);

  • the provided credentials are invalid and need to be updated;

  • we encounter a temporary error, as interfacing with constantly-evolving APIs or websites can be tough ;-)...

Synchronization statuses are available by connector in the Monitoring page of your domain, in the administration console.

Connection states

Connection stateActions to take

(null)

The synchronization was successful, no error.

SCARequired webauthRequired additionalInformationNeeded decoupled validating (transcient)

Synchronization is suspended because we need user consent or SCA to proceed. You should present this error prominently with an option to resume the connection using the indications below.

actionNeeded

Synchronization failed because the user needs to perform an action directly on the bank website or app (usually, accept new CGUs or similar one-time actions). You should present this error prominently, with the details in the error_message property.

passwordExpired

Synchronization failed because the user needs to renew its password on the bank website. You should present this error prominently and prompt the user for his new password afterwards.

wrongpass

Synchronization failed because the credentials we own are invalid or obsolete. You should present this error prominently with an option to recover the connection using the indications below.

rateLimiting

Synchronization failed because the target website or API is temporarily blocking synchronizations due to rate limiting. We will retry after a delay and connections in this state will be resumed automatically.

websiteUnavailable

Synchronization failed because the targeted API or website is temporarily unavailable. We will periodically retry to sync.

bug

Synchronization failed because of an error from our side. We monitor errors and do our best to fix them quickly. Connections in this state will be resumed automatically after the error is fixed.

For multi-sources connections, we expose the error of any source as an error of the whole connection so the integration can be simplified to checking the connection status. You can also handle the state property of each source directly.

Resume/recover connection sync

Some connection states require an interaction with the user in order to restore synchronization: additionalInformationNeeded, SCARequired, webauthRequired, wrongpass, decoupled. You should present recovery options in your app or service to engage the user into completing the required steps.

Since synchronization is suspended until the appropriate action is performed, we advise you to present such errors prominently in your service or app, using banners, indicators or notifications.

You have 2 options to handle connection resuming/recovery :

  • use the Reconnect webview;

  • build a custom experience and handle the different cases manually.

Use our Reconnect webview

GET /auth/token/code
{
  "code": "nc0EdV2MiVmSig1…",

}

The provided temporary code is valid for a few minutes. Then, present the following URL to your user (new lines are only added for clarity):

https://{domain}.biapi.pro/2.0/auth/webview/reconnect
  ?client_id={clientId}
  &code={authorizationCode}
  &connection_id={connectionId}
  &redirect_uri={yourCallbackUri}

Build a custom user experience

As an integrator you can also decide to create your own user experience to handle connection resuming. However, the implementation of all steps and cases is a complex task.

Custom implementations that include transmission of user credentials (login or password) require the Agent Status. The wrongpass state cannot be handled if you don't hold this status.

The steps to take and information to display/prompt depend on the state of the connection:

POST /connections/{connectionId}

The connection will be resumed or set to another error state that must be handled identically.

Example: GET /connections/{connectionId}

{
  "state": "additionalInformationNeeded", // or "wrongpass"
  "fields": [ { "name": "otp", "type": "text", "label": "Code d'autorisation", … } ],

}

User-provided OTP is to be sent to the API to resume the synchronization:

POST /connections/{connectionId}
{
  "otp": "123456"
}

The connection will be resumed or set to another error state that must be handled identically. Make sure you also handle the wrongpass error code that can be raised on posting the credentials.

POST /connections/{connectionId}
{
  "resume": true
}

The connection will be resumed or set to another error state that must be handled identically.

By default, this call will be blocking until validation, so you should handle timeouts in a loop, or implement polling on the client side thanks to the query parameter background=true. The connection is in the validating state during this step.

POST /connections/{connectionId}?background=true
{
  "resume": true
}
https://{domain}.biapi.pro/2.0/webauth-url
  ?client_id={clientId}
  &id_connection={connectionId}
  &redirect_uri={yourCallbackUri}

After the redirection, the connection will be resumed or set to another error state that must be handled identically.

  • If the connection is in another error state than above, recovering is not possible.

API calls that raise a synchronization perform a synchronous check of the credentials with the connector, so these requests usually take a few seconds. Make sure you handle them in a user-friendly way.

Last updated