Item lifecycle

During the connection to an institution, the item goes through different status & executionStatus as a step-by-step function, in which it will provide details on the process of the synchronization.

If you decide to use our Pluggy Connect widget, you won't require to go into further details of the flow - we've already it all covered up for you.

Synchronization flow

During the Item creation or update process, it goes through different states until the process is finished. Once the process has started, the status will be set to UPDATING and then there are a few possible state values that we'll detail below, based on the Connector login flow.

There are 3 login flow possibilities: when the connector doesn't require an MFA parameter, when the connector requires an MFA that is accessible by the user beforehand (ie. using Google Authenticator), or when the connector requires an MFA that is generated/requested to the user right after the initial login step has been completed.

1- Connectors without MFA parameter

This is the simplest case.
The login flow will proceed with just the user credentials.

A- If user credentials have been correct, then the connection will proceed and it will attempt to retrieve products data. Then:
1- if everything went well, the final Item status will be UPDATED, and the related executionStatus will be SUCCESS.
2- if something went wrong but at least some of the products data could be retrieved, the Item status will also be UPDATED, and the related executionStatus will be PARTIAL_SUCCESS. Further information about what has failed will be available in the Item executionReport field.
3- if something went fatally wrong with the connection, such as an unexpected error, and no data could be retrieved, the Item status will be OUTDATED and the related executionStatus will be ERROR.

📘

In the above cases, all items are considered updatable, since the initial credentials have been correct.
By default, updatable Items are automatically synced by us, once per day.

 
B- If user credentials have not been correct, then the Item status will be LOGIN_ERROR.

🚧

In this case the Item is not considered updatable. The user will have to manually trigger an update, and start over by providing a new set of credentials.

 

2- Connectors with 1-step verification step

This case of Connector can be identified by finding in one of the connector data credentials field values, a credential that has the mfa field set as true.

The same flow as in the previous step will occur.

🚧

Here Items are not updatable, since an extra input provided by the user is required for each connection execution.

Exceptions
There are a few exceptions, like Nuinvest, which allows us to continue syncing with the institution (with no more MFA requests), once the initial device authorization has been granted.

3- Connectors with a 2-step verification step

This case of Connector can be identified by checking the base connector data mfa field, set as true.

So, after providing the initial user credentials, if they have been correct, then the Item will jump to a different state: WAITING_USER_INPUT.

In this state, the connection will be suspended, until the user submits the validation code. Once the user sends the new parameter, if the parameter submitted was correct, the execution will resume as in the previous scenarios until the item finishes the execution in one of the three possible final states UPDATED, OUTDATED or LOGIN_ERROR.

🚧

This case of Items are not updatable, since an extra input provided by the user is required for each connection execution.

The only exception is Nubank, which can be updated after an initial device authorization.

Summary

The following state diagram summarizes the Item connection flow.

Execution step by step

Each item is created or updated through an execution, which, like the item, goes through different states as it is executed.

Each Item status is associated to a set of possible executionStatus values, according to the following diagram.

These combinations of statuses give specific information not only about the steps that are being executed while the Item is updating, but also about the final result of the execution. Thus, for example, if the item status is OUTDATED, we can check the related executionStatus value to know the specific cause of it not having finished successfully.