👍

Widget Update Mode

We really recommend that you use our Connect Widget with Update Mode after your receive a Link webhook event to handle the credentials or token update.

Invalid credentials

You can receive an invalid_credentials notification whenever a user's credentials are no longer valid to update a recurrent link. This can happen when a user changes their bank credentials.

Once you receive this notification, you can ask your user to update their new password using the Connect widget in Update Mode. As soon as the credentials are correct, the recurrent link is refreshed.

If you are not using the Connect Widget, you can ask your user to send you their new password and then perform a Link Update request to save the new password. For example, if you receive the following webhook:

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "LINK",
  "process_type": "recurrent_update",
  "webhook_code": "invalid_credentials",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "error_code": "login_error", // Webhook event error
    "error_message": "Invalid credentials provided to login to the institution", // Descriptive message of the error
    "status": 400
  }
}

Once you receive the required credentials from your user, make a PUT request to our Links endpoint with the updated details:

curl -X PUT https://api.belvo.com/api/links/{id} \
  -H 'Content-Type: application/json' \
  -H 'Host: api.belvo.com' \
  -H 'cache-control: no-cache' \
  -d '{
      "password": "{user_provided_password}"
  }' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Where:

• {id} is the link_id your receive in the webhook notification.
• {user_provided_password} is the updated password you receive from your user.

Token required

You can receive a token_required notification whenever a new MFA token is required by the institution to keep the recurrent link working.

📘

Handling MFA

For more information on how to handle MFA, check out our dedicated MFA guide.

Once you receive this notification, you can ask your user to provide a new token using the Connect widget in update mode. As soon as the token is provided, the recurrent link is refreshed.

Please note that until the link is updated, Belvo will not send any webhook relating to this link.

If you are not using the Connect Widget, you can ask your user to send you their new password and then perform a Link Update request to provide the new MFA token. For example, if you receive the following webhook:

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "LINK",
  "process_type": "recurrent_update",
  "webhook_code": "token_required",
  "link_id": "30cb4806-6e00-48a4-91c9-ca55968576c8",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "error_code": "token_required", // Webhook event error
    "error_message": "MFA token was required by the institution", // Descriptive message of the error
    "status": 428,
    "session": "2675b703b9d4451f8d4861a3eee54449",
    "expiry": 9600,
    "token_generation_data": {
      "instructions": "Use this code to generate the token",
      "type": "numeric",
      "value": "12345"
    }
  }
}

Once you receive the required token credentials from your user, make a PATCH request to our Links endpoint with the updated token:

curl -X PATCH https://api.belvo.com/api/links/ \
  -H 'Content-Type: application/json' \
  -H 'Host: api.belvo.com' \
  -H 'cache-control: no-cache' \
  -d '{
    "session": "{sessionId}",
    "token": "{userToken}",
    "link": "{linkId}"
}' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Where:

• {sessionId} is the session you receive in the webhook notification.
• {userToken} is the new token you receive from your user.
• {linkId} is the link_id your receive in the webhook notification.