Item lifecycle
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.
Item Status
To understand the current status of an item, we must review its status field. This will give a first glance about the connection's health.
| Value | Description | Meaning |
|---|---|---|
| UPDATING | The connection is syncing with the provider. | An update process is in progress and will be updated soon. |
| LOGIN_ERROR | The sync process finished with errors. | The connection must be updated to execute again. We won't trigger auto-sync updates until new credentials parameters are provided. |
| OUTDATED | The sync process finished with errors. | The parameters were correctly validated, but there was an error in the last execution. It can be retried. |
| WAITING_USER_INPUT | The sync process needs user's input to continue. | The connection requires user's input to continue the sync process, this is common for MFA authentication connectors. |
| UPDATED | The sync process finished successfully. | The last sync process has completed successfully and all new data is available to collect. |
As mentioned above, when we trigger an update, the connection status will be set to UPDATING. This is an in-progress status which means you will need to check it again in a couple of seconds.
If the credentials sent were invalid, you will encounter a LOGIN_ERROR status and will be required to update it while also providing new credentials.
In case there was an unexpected error, you will encounter the OUTDATED status, and you will have to review the executionStatus field for further details.
Finally, the most common scenario, is the UPDATED status, which means that the connection was successfully synced with the institution.
Execution Status 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.
You can review the detailed Item's current execution status through this field, executionStatus.
This value indicates the current step the execution is at, which can be a transitive (in-progress) state, or a final state.
Transitive states
The following states represent that the Item execution is still running, so it's likely it will continue to change by itself.
| Value | Description |
|---|---|
| CREATED | The connection was successfully initiated. |
| LOGIN_IN_PROGRESS | The connection is currently in the Login authentication step. |
| LOGIN_MFA_IN_PROGRESS | The connection is currently in the second Login authentication step. This state happens after submitting an MFA token parameter only. |
| ACCOUNTS_IN_PROGRESS | Currently collecting Accounts data. Implies Login step has just been completed. |
| CREDITCARDS_IN_PROGRESS | Currently collecting Credit Cards data. Implies Accounts collection step has just been completed (or skipped). |
| TRANSACTIONS_IN_PROGRESS | Currently collecting Accounts and Credit Cards Transactions data. Implies Credit Cards collection step has just been completed (or skipped). |
| INVESTMENT_TRANSACTIONS_IN_PROGRESS | Currently collecting Investment Transactions. Implies Transactions collection step has just been completed (or skipped). Note: only few connectors support this product. |
| PAYMENT_DATA_IN_PROGRESS | Currently collecting Transactions Payment data. Implies Investment Transactions collection step has just been completed (or skipped). Note: only few connectors support this product. |
| IDENTITY_IN_PROGRESS | Currently collecting Identity data. Implies Transactions (and Payment Data, if any) steps have just been completed (or skipped). |
| OPPORTUNITIES_IN_PROGRESS | Currently collecting Opportunities data. Implies Identity steps have just been completed (or skipped). |
| MERGING | Analyzing and storing all the collected data. Implies all of the available Institution data has been collected. |
Final states
These states represent an Execution that has finished running.
We can distinguish two possible types of final states:
- A finished state, either with a success, or error result.
- An intermediate state, which means more input from the User is needed. In this case, a new Execution needs to be started by fulfilling the required actions.
Success states
| Value | Description |
|---|---|
| SUCCESS | The execution was completed successfully, products have been collected. |
| PARTIAL_SUCCESS | The execution was completed successfully, products has been collected, but some of them have failed. Check the Item statusDetail attribute for more information. |
Error state
| Value | Description |
|---|---|
| ERROR | There was an unexpected error in the connection. |
| MERGE_ERROR | The connection has finished successfully and data has been collected, but we had an unexpected error storing it in our records. |
| INVALID_CREDENTIALS | Couldn't authenticate to the user Institution's account due to incorrect credentials. |
| ALREADY_LOGGED_IN | Couldn't login because there is an active session and the Institution didn't allow creating a new one. |
| SITE_NOT_AVAILABLE | Failed to get a response from the Institution's site. Possibly it has went into maintenance, out of service, or temporarily unavailable. |
| INVALID_CREDENTIALS_MFA | The second login step failed due to an incorect or expired MFA token parameter provided. |
| USER_INPUT_TIMEOUT | The second login step has been aborted after the MFA parameter request has timed out. |
| ACCOUNT_LOCKED | Couldn't login because the user's account has been locked. User needs to get in contact with the Institution to unlock it. |
| ACCOUNT_NEEDS_ACTION | Couldn't proceed with the data collection because a manual user action is needed, such as resolving an Institution's request of accepting new Terms of Use, providing more/new personal information, or else. |
| USER_NOT_SUPPORTED | Pluggy currently doesn't support the kind of account the user is currently trying to connect, for the selected institution. For example, an "Operador" account in Caixa Business connector. |
| ACCOUNT_CREDENTIALS_RESET | The financial institution is requesting to reset the credentials of the user, this could happen due to an expired password or new security measures implemented by the institution. |
| CONNECTION_ERROR | Failed to establish a connection to the Institution's site. |
| USER_AUTHORIZATION_NOT_GRANTED | Couldn't proceed with data collection because the User has not granted Device authorization to the Pluggy Connector. |
| USER_AUTHORIZATION_REVOKED | The user removed the consent to share their data in the Financial Institution. |
Intermediate states
| Value | Description |
|---|---|
| WAITING_USER_INPUT | After a successful initial login step, the Institution is expecting an additional user's input to continue the execution, ie. an extra MFA token parameter. More info here. |
| USER_AUTHORIZATION_PENDING | A special case, similar to the ACCOUNT_NEEDS_ACTION, but in this scenario the User needs to provide manual authorization in his Device or Institution's account. Once the user resolves this, Pluggy will proceed with the data collection automatically a few minutes later, no more external action is needed. |
See Items in our API reference for more information.
Synchronization flow
During the process of creating or updating an Item, it will go through different states until the data collection is finished.
When the process starts, the status will be set to UPDATING and from there, there are a few possible state values that we'll detail below, based on the Connector-specific login flow.
There are 3 Connector-specific 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.
In cases in which MFA parameter is sent repeated between executions, API will return a bad request with the specific message without execute the connector.
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.
Updated 7 months ago