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.

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.

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).

PAYMENT_DATA_IN_PROGRESS

Currently collecting
Transactions Payment data.
Implies 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).

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.

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.

 

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.

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