You can use the Connect widget to update a link that requires a new password or a new MFA token.

Why do links need to be updated?

There are some scenarios where a link needs to be refreshed:

• The password connected with the Link has been changed by the user.
• The institution requires a new MFA token to login.

How do I know if a link needs to be updated?

A link will need to be updated in the following scenarios:

Scenario 1: you receive an error from the API

When doing a POST call to our API, you can receive errors meaning that the link needs to be updated:

Scenario 2: you receive a webhook error for a recurrent link

During the daily refresh of your recurrent links, we will send an event in case one of your links needs to be updated to be refreshed.

How can I use the Connect widget to update a link?

Once you have a link you want to update, you should give your end-user a way to update the link. This can be as easy as adding an "update" button in your application that will open the widget in update mode for that invalid link.

To open the widget in update mode, we just need you to include the link_id in your new access token to your widget integration.

Once you receive an error message, you should send your end-user a notification to ask for a link update (this can be as easy as adding a button pointing to your application that will open the widget in update mode for that link).

To open the widget in update mode, we just need you to include the link_id in your new access token to your widget integration.

For example:

curl -X POST \
  https://api.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -H 'Host: api.belvo.com' \
  -d '{
    "id": "SECRET_ID",
    "password": "SECRET_PASSWORD",
    "link_id": "LINK_ID",
    "scopes": "read_institutions,write_links,read_links"
  }'

# check our python-client library on github
# https://github.com/belvo-finance/belvo-python
from belvo.client import Client

client = Client("my-secret-key-id", "my-secret-key-password",  "https://sandbox.belvo.com")

token = client.WidgetToken.create(link="my-link-id")

# check our Ruby gem on github
# https://github.com/belvo-finance/belvo-ruby
require 'belvo'

client = Belvo::Client.new(
  "my-secret-key-id", 
  "my-secret-key-password",
  "https://sandbox.belvo.com"
)

client.widget_token.create(options: {link: "my-link-id"})

// check our node package on github
// https://github.com/belvo-finance/belvo-js
var belvo = require('belvo').default;

var client = new belvo(
  'my-secret-key-id',
  'my-secret-key-password',
  'https://sandbox.belvo.com'
);

client.connect()
  .then(function () {
        client.widgetToken.create({ link: 'my-link-id' })
      .then((response) => {
      res.json(response);
        })
      .catch((error) => {
      res.status(500).send({
        message: error.message
      });
    });
});

We will take care of checking which kind of link update needs to be triggered (token or credentials) and will guide the user through the process.

What happens once the link is updated?

Once a recurrent link is successfully updated, the link status is valid again and the link_id remains the same. You’ll receive in the widget a successful callback response.

📘

If the successfully updated link is a recurrent one, we automatically trigger an update of the link. If we find fresh data, you’ll receive historical update webhooks.

What happens if there is an error when updating the link?

You’ll keep receiving success and error callbacks in the widget as usual.
Link status won’t be valid again until it’s been successfully updated.

How can I know which links need to be updated?

Using link listing and checking the link status, you can see which links need to be updated by your users.
If the link status is invalid, token_required it needs to be updated.

For example:

# invalid links
curl -u Secret-Key-ID:Secret-Key-PASSWORD  \
https://api.belvo.com/api/links/?status=invalid

# token required links
curl -u Secret-Key-ID:Secret-Key-PASSWORD  \
https://api.belvo.cmo/api/links/?status=token_required

curl -u [Secret Key ID]:[Secret Key PASSWORD]  \
https://api.belvo.com/api/links/[LINK ID]/

curl -u [Secret Key ID]:[Secret Key PASSWORD]  \
https://api.belvo.com/api/links/

How can I test the widget in update mode?

Use the Heimdall institution in our sandbox environment. After you register a link with the institution, any additional POST calls made to the institution will return a 428 Token Required response, where the status of the link will be changed to token_required.

Then all you need to do is pass the link_id when you start the widget, and when you successfully provide the necessary credentials, the link status will be updated to valid again.