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

When synchronization fails, we update the state property of the connection resource with an error code that reflects the situation. As an integrator, you should handle this state and guide the user into recovering from the situation.

Connection state	Actions 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

Our webview has a dedicated endpoint for connection resuming. It will take care of guiding the user and prompting him the required information if needed.

To present the webview, first obtain a temporary code to secure the transaction:

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}

After the webview flow is complete (either successfully or with an error), the user will be redirected to your callback URL, and the connection state will be updated accordingly.

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:

• If the connection is in the SCARequired state, the synchronization has not been attempted because it requires an explicit user consent. Force the connection (with no parameter) to trigger the approval demand:

POST /connections/{connectionId}

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

• If the connection is in the additionalInformationNeeded or the wrongpass state, the user must be prompted for the required values that are described in the fields property of the connection. The provided values must be posted on the connection, and the synchronization will resume.

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.

• If the connection is in the decoupled state, an authorization is required using a third-party SCA mechanism (validation in an app or using a dedicated device). In this case you should display a waiting message and send a resuming signal to our API:

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
}

• If the connection is in the webauthRequired state, the user has to complete authorization in a browser. You should obtain a webauth recover URL for the connection, and let the user navigate to it:

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.