Updating an Item

In this guide, we'll show you how to update an existing Item using our Connect widget.

After creating an Item successfully, you'll probably want to continue to collect the products data that continues to appear in the next days.

To achieve this, instead of creating a whole new Item from scratch (in which we collect all the data from the last 365 days) you can instead just trigger an update for your existing Item reference.

This is a much more cost-efficient process, as when doing this we'll only retrieve the institution products data that has been generated right after the last time we did the previous collection process. We'll even collect a few days before that, just to make sure we won't miss any changes or additions that could've happened recently.

📘

Note

We provide automatic Item updates, for Production applications, every 24/12/8 hours, based on your plan.

In most cases, you can simply start the Item Update process without any problem or further input from the user.

However, there are some scenarios where this is not possible, due to limitations related to extra authentication requirements from the Instutition (such as a MFA requirement), or due to the Item having an invalid credentials state which requires new credentials input from the user.

These scenarios are the following:

  • Items that could not succeed due a problem with their credentials (Item status: INVALID_CREDENTIALS).
  • Items that are not able to auto-sync by Pluggy on our daily synchronization process, due to the connection needing an extra input from the user, such as a MFA parameter.

To open Pluggy Connect in this update mode, you need to:

  1. Create a new Connect Token, specifying the itemId parameter of the corresponding Item connection we want to refresh. This detail is necessary to let us properly validate that you are authorized to access and udpate this specific Item.

  2. Pass it to Connect, both the recently created connectToken, and the corresponding Item id through the updateItem property.

Then, If there is no further input from the user required, Pluggy Connect will just start the update process.
Otherwise, when new credentials and/or a MFA parameter is required, Pluggy Connect will prompt them to the user to complete, after which the update process will begin.

👍

Code Example

Check out a full standalone HTML example in our recipe: Update an Item using Pluggy Connect.

Case: INVALID_CREDENTIALS

This happens when:

  • The credentials provided by the user have not been correct, for example due to an incorrect input.
  • The credentials were correct, but when we tried to auto-sync the Item by reusing the last valid credentials, we found an invalid login error.

For any of these situations, the user will need to use Pluggy Connect to update this Item and provide new credentials.

After this, if the login step succeeded, any further update of this Item will just reuse the newly provided credentials and our auto-sync process will resume working again.

Case: Item not auto-syncheable

This is the case for institutions that require an extra MFA login step.

In this scenario, the only option for the Item to be updated, is to have the User open Pluggy Connect configured for the corresponding Item, and have him/her solve the required MFA challenge as needed.

Some examples are:

  • XP
  • Bradesco
  • Easynvest
  • Rico Investimentos

You can find in the complete list of Connectors which ones require an MFA.

📘

Note

There are some institutions that only require an initial verification or device authorization as a MFA only for the first time. After this, no more manual input is needed from the User, so we'll be able to auto-sync these Items as well.


Syncing the Data after Update

Once an update has been completed, the item will change its status to UPDATED, and will trigger the item/updated webhook.

It's expected that our customers implement a Sync process after the webhook to sync the data.

Usually the most frequent question, is how to sync transactions, check out this guide for more information.