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.

ValueDescriptionMeaning
UPDATINGThe connection is syncing with the provider.An update process is in progress and will be updated soon.
LOGIN_ERRORThe 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.
OUTDATEDThe 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_INPUTThe 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.
UPDATEDThe 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.

28802880

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.

ValueDescription
CREATEDThe connection was successfully initiated.
LOGIN_IN_PROGRESSThe connection is currently in the Login authentication step.
LOGIN_MFA_IN_PROGRESSThe connection is currently in the second Login authentication step. This state happens after submitting an MFA token parameter only.
ACCOUNTS_IN_PROGRESSCurrently collecting Accounts data.
Implies Login step has just been completed.
CREDITCARDS_IN_PROGRESSCurrently collecting Credit Cards data. Implies Accounts collection step has just been completed (or skipped).
TRANSACTIONS_IN_PROGRESSCurrently collecting Accounts and Credit Cards
Transactions data.
Implies Credit Cards collection step has just been completed (or skipped).
INVESTMENT_TRANSACTIONS_IN_PROGRESSCurrently collecting Investment Transactions.
Implies Transactions collection step has just been completed (or skipped).
Note: only few connectors support this product.
PAYMENT_DATA_IN_PROGRESSCurrently collecting Transactions Payment data.
Implies Investment Transactions collection step has just been completed (or skipped).
Note: only few connectors support this product.
IDENTITY_IN_PROGRESSCurrently collecting Identity data.
Implies Transactions (and Payment Data, if any) steps have just been completed (or skipped).
OPPORTUNITIES_IN_PROGRESSCurrently collecting Opportunities data.
Implies Identity steps have just been completed (or skipped).
MERGINGAnalyzing 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

ValueDescription
SUCCESSThe execution was completed successfully, products have been collected.
PARTIAL_SUCCESSThe execution was completed successfully, products has been collected, but some of them have failed. Check the Item statusDetail attribute for more information.

 

Error state

ValueDescription
ERRORThere was an unexpected error in the connection.
MERGE_ERRORThe connection has finished successfully and data has been collected, but we had an unexpected error storing it in our records.
INVALID_CREDENTIALSCouldn't authenticate to the user Institution's account due to incorrect credentials.
ALREADY_LOGGED_INCouldn't login because there is an active session and the Institution didn't allow creating a new one.
SITE_NOT_AVAILABLEFailed to get a response from the Institution's site. Possibly it has went into maintenance, out of service, or temporarily unavailable.
INVALID_CREDENTIALS_MFAThe second login step failed due to an incorect or expired MFA token parameter provided.
USER_INPUT_TIMEOUTThe second login step has been aborted after the MFA parameter request has timed out.
ACCOUNT_LOCKEDCouldn't login because the user's account has been locked. User needs to get in contact with the Institution to unlock it.
ACCOUNT_NEEDS_ACTIONCouldn'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.
CONNECTION_ERRORFailed to establish a connection to the Institution's site.
USER_AUTHORIZATION_NOT_GRANTEDCouldn't proceed with data collection because the User has not granted Device authorization to the Pluggy Connector.

 

Intermediate states

ValueDescription
WAITING_USER_INPUTAfter 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_PENDINGA 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.

28802880