This articles refers to the multi-region widget
The content of this article refers to the multi-region widget (applicable for Mexico). If you wish to operate in Brazil, please see our Connect Widget for Regulated OFDA.
br
# Introduction
Belvo offers a plug-and-play Connect Widget solution, both for web and mobile applications, that provides a secure and optimized authentication process for each institution. The Connect Widget is the smoothest way for your users to connect their bank account within your application. It is compatible with our aggregation products: Banking, Employment, and Fiscal.
If you'd like to test out how it works, check out our Widget Demo.
Here is a preview of the Connect widget on a demo website:

## Flow (Multi Region)
The end-to-end integration involves your frontend and backend. Below is an overview of how you can create links with the Connect widget.
As you can see, your client-side and server-side will be involved in the Connect Widget flow. Here is an end-to-end example to illustrate each side's responsibility:
1. Your user clicks a **Add a bank account** button within your application.
2. Your frontend calls your backend to request an `access_token` from Belvo.
3. Your backend calls Belvo to get an `access_token`.
4. Belvo returns a valid `access_token` to your backend.
5. Your server returns the `access_token` to your frontend.
6. Your frontend starts the widget using the `access_token`.
7. The user navigates through the Connect Widget and creates a valid link to their institution.
8. Belvo returns the newly created link `id` via an event callback to your frontend. Belvo will then start asynchronously retrieving the historical data for the link.
9. Belvo sends a webhook to your backend once data is available for each core resource.
10. Your backend retrieves the data using a GET call, passing the link `id` as a query parameter.
11. Belvo returns the info to your backend and forwards it to your frontend.
12. Your user sees their financial data within your service.
> ❗️ Server-side calls
Our API cannot be used directly from the frontend. The access token and any other API request you need should be handled from your backend (server-side).
br
# Embed the Connect widget snippet
To embed the widget code in your application, the following code elements to the page where the Connect Widget should appear (if you are working in Angular, React, or Vue, just select the relevant code tab for you).
```html
...
...
...
...
...
...
```
```javascript
import { Component, OnInit } from '@angular/core';
// Implement the OnInit interface to be able to load the script
@Component({
selector: 'app-root',
template: `
`,
styleUrls: ['./app.component.css']
})
export class AppComponent implements OnInit {
title = 'widget-angular';
// implemented method
ngOnInit(): void {
loadScript('https://cdn.belvo.io/belvo-widget-1-stable.js');
}
}
// Please add the code from Step 3 here.
```
```javascript
import './App.css';
import { useEffect } from "react";
function App() {
useScript('https://cdn.belvo.io/belvo-widget-1-stable.js');
return (
);
}
export default App;
// Hook
function useScript(src) {
useEffect(
() => {
// Create script
const node = document.createElement('script');
node.src = src;
node.type = 'text/javascript';
node.async = true;
node.onload = createWidget
// Add script to document body
document.body.appendChild(node);
},
[src] // Only re-run effect if script src changes
)
}
```
```html
```
> 🚧 Make sure you include the **reference** to `https://cdn.belvo.io/belvo-widget-1-stable.js`. Otherwise, the widget will not load in your app!
# Generate an `access_token`
> 👍 Customizing the`access_token`
When you request your `access_token`, you can pass additional parameteres to customize the appearance of your widget. For more information, see our Branding and customization guide.
> ❗️ Server-side request
The `access_token` request **must** be done from your server-side in order to protect your API keys secretId and secretPassword). So if you're using a framework like Vue or React, please make sure that you generate the request from your server-side.
In order for the widget to appear to your end users, you need to generate an `access_token` in your server-side and send it to Belvo. Once we receive the request, you'll receive an object with two elements: `access` and `refresh`. Pass the value of the `access` element to your client-side, and you'll be able to start the widget.
The returned values are valid for **10** minutes and can be sent to your frontend to start the Connect Widget. We invalidate the token as soon as your user successfully connects their account.
To generate an `access_token`, simply make a call from your server-side to Belvo (see the example below):
```shell
curl -X POST \
https://sandbox.belvo.com/api/token/ \
-H 'Content-Type: application/json' \
-H 'Host: sandbox.belvo.com' \
-d 'See payload example below'
```
```json
{
"id": "SECRET_ID",
"password": "SECRET_PASSWORD",
"scopes": "read_institutions,write_links",
"fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"],
"credentials_storage": "store",
"stale_in": "300d"
}
```
> 📘 Scopes
Remember to pass the `scopes` parameter when generating your access token otherwise the widget will not start correctly. Those scopes are necessary to give the right permissions to the token for the widget to work.
`"scopes": "read_institutions,write_links"`
After you make your call, Belvo returns an object from which you'll need the value from the `access` key. You'll send this value to your client-side so that the widget can actually start.
```json
{
"access": "{access_token_for_widget}", // You'll need this value to send to your client-side
"refresh": "{refresh_token}"
}
```
✳️ OK! Now that you can generate `access_token`, you can start the widget!
# Start the Connect widget
Using this `access_token` you can now start the Connect widget:
```javascript
// Code to be included within your
```
## Event callback
When users encounter certain events in the widget, we'll send you some data to explain what's going on. The data object will contain an `eventName`, `request_id`, and `meta_data` object.
```json
{
"data": [
{
"eventName": "ERROR",
"request_id": "UUID",
"meta_data": {
"error_code": "login_error",
"error_message": "Invalid credentials provided to login to the institution",
"institution_name": "bancoazteca_mx_retail",
"timestamp": "2020-04-27T19:09:23.918Z"
}
}
]
}
```
```json
{
"data": [
{
"eventName": "WARNING",
"request_id": "UUID",
"meta_data": {
"warning_code": "institution_disabled",
"warning_message": "The institution is temporarily unavailable.",
"institution_name": "bancoazteca_mx_retail",
"timestamp": "2020-04-27T19:09:23.918Z"
}
}
]
}
```
```json
{
"data": [
{
"eventName": "PAGE_LOAD",
"meta_data": {
"page": "/institutions", // Page that the user is directed to
"from": "/consent", // Page where the user was previously
"institution_name": "" // Note: This field only appears AFTER they've selected an institution
}
}
]
}
```
**event_name**
A string representing the name of event that has just occurred in the widget.
| Event type | Description |
| --- | --- |
| `ERROR` | When a recoverable error occurred in the widget, see the `error_code` and `error_message` in the `meta_data`. |
| `WARNING` | When a user tries to connect to an institution that is currently unavailable. See the `warning_code` and `warning_message` in the `meta_data` for more information. |
| `PAGE_LOAD` | When a user progresses to the next screen in the widget. |
**request_id**
A string used to uniquely identify the error.
> 🚧 Store the request_id
When implementing your Belvo integration, make sure that you account for storing the request_id when you receive an error. This way, when you provide our engineers the ID, they can troubleshoot the issue quickly and get you back up and running.
**meta_data**
An object containing more information about the event that has just occurred in the widget.
The `meta_data` object can have the following properties:
| Parameter | Description |
| --- | --- |
| `error_code` | The error code that the user encountered. See the Exit callback for the list of possible error codes. |
| `error_message` | The error message that the user encountered. See the Exit callback for the list of possible error messages. |
| `institution_name` | The selected institution |
| `timestamp` | A timestamp of when the event occurred |
```html
```
## Exit callback
When users decide to close the widget, we'll send you some data to explain what's going on. The data object will contain a `last_encountered_error` object and `meta_data` object.
> 👍 Real-world use case
Monitoring for the Exit callback is useful as based on the event, you can redirect your user to a particular screen after they close the widget.
```json
{
"data": [
{
"last_encountered_error": {
"message": "Invalid credentials provided to login to the institution",
"code": "login_error"
},
"meta_data": {
"institution_name": "erebor_mx_retail",
"step": "abandon-survey"
}
}
]
}
```
**last_encountered_error**
The `last_encountered_error` object is only sent if an error occurred. See the table below for a list of possible error codes and their messages.
| Error code | Error message |
| --- | --- |
| `institution_down` | The financial institution is down, try again later |
| `login_error` | The possible error messages for a login_error are: - Invalid credentials provided to login to the institution The user account is locked, user needs to contact the institution to unlock it The user account access was forbidden by the institution Impossible to login, something unexpected happened while logging into the institution. Try again later. A MFA token is required by the institution, but it’s not supported yet by Belvo. Login not attempted due to invalid credentials Missing credentials to login to the institution |
| `too_many_sessions` | Impossible to login, a session is already opened with the institution for these credentials |
| `unexpected_error` | Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution |
**meta_data**
The `meta_data` object is sent whenever a user exits the widget. See the table below for a list of possible values.
| Parameter | Description |
| --- | --- |
| `step` | Sent when the user exits the widget at the initial screen. The value of the parameter is always `abandon-survey`. |
| `institution_name` | Sent when the user exits the widget after selecting an institution. The value will be Belvo's institution code, for example `banamex_mx_retail`. |
Here is an example of onExit usage:
```html
```
# Use the `link_id` to get data
Once your user successfully connects their bank account, you'll receive the `link_id` in the success event. Belvo will then send you webhooks informing you when information is ready for the link. For more information, see:
- Asynchronous Workflows (Single Links)
- Asynchronous Workflows (Recurrent Links)
br
# Connect widget update mode
The Connect widget can be configured in “update mode” to restore a link that has temporarily stopped working because:
- the password connected with the Link has been changed by the user
- a new MFA token is required
For more information, check our guide to Update a link using the Connect widget.