Learn how the Connect widget works and how to integrate it in your website.
Belvo offers a plug and play Connect widget that provides a secure and optimized authentification process for each institution.
The Connect widget is the smoothest way for users to connect their bank account within your application. It is compatible with our 3 products: Banking, Fiscal and Gig economy.
Here is a preview of the Connect widget on a demo website:


Connect widget overview
The end-to-end integration involves frontend-side and server-side configurations. 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 both be involved in the Connect widget flow.
Here is an end-to-end example to illustrate each side's responsibility:
- An end user clicks on a button to "Add a bank account"
- The client-side calls the server-side asking it to get an
access_token
- The server-side calls Belvo to get the
access_token
using your private API keys - Belvo returns a valid
access_token
to your server-side - The server returns the
access_token
to the client-side - The client-side starts the widget using the
access_token
- The end user navigates through the Connect widget and creates a valid link
- Belvo returns the newly created
link_id
via callback to your client-side - The client-side calls your server-side to pull first financial data from Belvo
- The server-side calls Belvo to retrieve financial information using the
link_id
and the private API keys - Belvo returns the info to the server-side, which then sends the info to the client-side
- The end user sees its financial data within your service
Server-side calls
Our API can't be used directly from the frontend. The access token and any other API request you need should be handled server-side by your own application.
If you are developing an asynchronous application (Ajax), then you should create the necessary endpoints to get access token and other data from.
If you are developing a synchronous application, then you should make the API requests from the backend and inject the data or access token into your HTML output.
Connect widget integration
1. Enable your website domain
For security reasons, the Connect widget can only be started from trusted domains in your account.
Therefore, you need to add your application's domain to the list of allowed URLs in your account:
- Log in to the dashboard and go to https://dashboard.belvo.co/configuration/widget/
- Click on the top right "ADD URL" button
- Add your application domain (for example "https://www.acme-corp.com")
Use a domain name and do not add a "/" at the end of the URL
Remember to use just domain names (eg.
https://www.acme-corp.com
) without the path portion.
Additionally, you don't need to add a "/" at the end of your domain. Adding it may result in the widget not working properly.This is an example of valid URL:
https://www.acme-corp.com
This URL will not be valid:https://www.acme-corp.com/home/start.html
2. Embed the Connect widget snippet
Once your application domain is added as an allowed URL, you can integrate the widget code to your frontend application.
Add the following elements to your hosting page(s) of the Connect widget:
<head>
...
<script src="https://cdn.belvo.io/belvo-widget-1-stable.js" async></script>
...
<head>
<body>
...
<div id="belvo"></div> <!-- anywhere inside the body -->
...
<body>
<body>
...
<script type="text/javascript">
const widget = document.createElement('script');
widget.setAttribute('src','https://cdn.belvo.io/belvo-widget-1-stable.js');
document.body.appendChild(widget);
</script>
...
<body>
<!-- Important information -->
<!-- To use the head method you will need to install the following dependency npm i --save vue-head -->
<!-- Then you will need to add it to vue -->
<!--
import Vue from 'vue'
import App from './App.vue'
import router from './router'
import store from './store'
import VueHead from 'vue-head'
Vue.use(VueHead)
new Vue({
router,
store,
render: h => h(App)
}).$mount('#app')
-->
<template>
<div>
<div id="belvo"></div>
<input type="button" @click="openWidget" value="Abrir Widget">
</div>
</template>
<script>
export default {
name: 'belvo',
head() {
return {
script: [
{src: 'https://cdn.belvo.io/belvo-widget-1-stable.js'},
]
}
},
methods: {
openWidget() {
let access_token = "acess_token";
// eslint-disable-next-line no-undef
belvoSDK.createWidget(access_token, {
locale: 'es', // 'en' for English or 'pt' for Portuguese
company_name: "ACME Corp", // the name of the company to be displayed in the first screen
//institution: 'banamex_mx_retail', // to start the widget directly on a specific institution credentials page
//institution_types: ['fiscal', 'retail', 'business', 'gig'], // to select the type of institution to show in the widget
// access_mode: "recurrent", // to specify the type of link to be created from the widget
country_codes: ['MX', 'CO', 'BR'],
callback: (link, institution) => this.successCallbackFunction(link, institution),
// onExit: (data) => this.onExitCallbackFunction(data),
// onEvent: (data) => this.onEventCallbackFunction(data)
}).build();
},
successCallbackFunction (link, institution) {
// do something with link and institution
},
// onExitCallbackFunction (data) {
// do something with data
// },
// onEventCallbackFunction (data) {
// do something with data
// }
}
}
</script>
3. Generate an access_token
Next, you need to generate an access_token
from your server-side.
Generate from server-side
To protect your API keys (secretId and secretPassword), this token MUST be generated from your server-side.
Here are examples to generate the access_token
using cURL or our official libraries:
# 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.co")
token = client.WidgetToken.create()
# 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.co"
)
client.widget_token.create
// 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.co'
);
client.connect()
.then(function () {
client.widgetToken.create()
.then((response) => {
res.json(response);
})
.catch((error) => {
res.status(500).send({
message: error.message
});
});
});
curl -X POST \
https://api.belvo.co/api/token/ \
-H 'Content-Type: application/json' \
-H 'Host: api.belvo.co' \
-d '{
"id": "[SECRET_ID]",
"password": "[SECRET_PASSWORD]",
"scopes": "read_institutions,write_links,read_links,delete_links"
}'
The returned token
is an object of two elements (access & refresh). The widget will need the access
element in order to be opened.
Scopes
If you are not using one of our official libraries, 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,read_links,delete_links"
If you are using Belvo official libraries, the scopes are already managed automatically.
The generated access_token
will be valid for 15 minutes and can be sent to your frontend to start the Connect widget.
4. Start the Connect widget
Using this access_token
you can now start the Connect widget:
<script type="text/javascript">
function onEventCallbackFunction (data){
// Do something with the event data
}
function onExitCallbackFunction (data){
// Do something with the exit data
}
function successCallbackFunction (link_id, institution) {
// Do something with the link_id or institution name
}
function openBelvoWidget() {
// call the server to generate an access token to start the widget
// you will need the "access" token (not the "refresh" token).
// For example:
// var token = getAccessTokenFromServer();
// var access_token = token.access;
belvoSDK.createWidget(access_token, {
locale: 'es', // 'en' for English or 'pt' for Portuguese
company_name: "ACME Corp", // the name of the company to be displayed in the first screen
//institution: 'banamex_mx_retail', // to start the widget directly on a specific institution credentials page
//institution_types: ['fiscal', 'retail', 'business', 'gig'], // to select the type of institution to show in the widget
// access_mode: "recurrent", // to specify the type of link to be created from the widget
country_codes: ['MX', 'CO', 'BR'],
callback: (link, institution) => successCallbackFunction(link, institution),
onExit: (data) => onExitCallbackFunction(data),
onEvent: (data) => onEventCallbackFunction(data)
}).build();
}
document.getElementById("myButton").onclick = openBelvoWidget;
</script>
Widget parameters
It is possible to use different parameters while starting the widget to customize the experience:
Parameter | Description |
---|---|
| You can pass your company or application name to customize the message displayed in the first screen: By default, without any company_name, the message will be "Vincula tu cuenta". |
| If you want to start the widget directly on a specific institution credential screen, you can pass an institution as a parameter. Example: By default, without any institution given, the widget is started on the list of institutions. |
| You can filter the type of institutions you want to see in the list using the By default, the widget is started with all types of institutions supported by Belvo. |
| You can filter the countries you want to see in the list of institutions using the Example: By default, the widget is started with all countries supported by Belvo. |
| You can define the locale to be used by the widget. Example: By default, the widget is started with 'es' as locale |
| You can define the type of link you want to create from the widget. Read more about our different type of links here: difference between single and recurrent link. Example: Default |
Widget callbacks
Success callback
You can specify a callback to be called when the link was created successfully.
This callback will return an object with two elements, a link
string and an institution
string.
Parameter | Description |
---|---|
| The link_id created in the widget |
| The name of the institution for this created link |
Here is an example of success callback usage:
<script type="text/javascript">
function successCallbackFunction (link_id, institution) {
// Do something with the link_id or institution name
}
function openBelvoWidget() {
...
belvoSDK.createWidget(access_token, {
...
callback: (link, institution) => this.successCallbackFunction(link, institution),
...
}).build();
}
</script>
onExit callback
You can specify a callback to be called when the user closes the widget.
This callback will return an object with two elements, a nullable last_encountered_error
object and a meta_data
object.
Parameter | Description |
---|---|
| A nullable object that contains the
|
| An object containing information about the
|
Here is an example of onExit usage:
<script type="text/javascript">
function onExitCallbackFunction (data) {
// Do something with the exit data
// data = {
// "last_encountered_error": {
// "message": "Link already exists.",
// "code": "invalid"
// },
// "meta_data": {
// "institution_name": "banamex_mx_retail",
// "step": "credentials"
// }
// }
}
function openBelvoWidget() {
...
belvoSDK.createWidget(access_token, {
...
onExit: (data) => this.onExitCallbackFunction(data),
...
}).build();
}
</script>
onEvent callback
You can specify a callback to be called when specific events occur within the widget.
This callback will return an object with two elements, an eventName
and a meta_data
object.
Parameter | Description |
---|---|
| A string representing the name of event that has just occurred in the widget.
|
| An object containing more information about the event that has just occurred in the widget.
|
Here is an example of onEvent usage:
<script type="text/javascript">
function onEventCallbackFunction (data) {
// Do something with the event data
// data = {
// "eventName": "ERROR",
// "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"
// }
// }
}
function openBelvoWidget() {
...
belvoSDK.createWidget(access_token, {
...
onEvent: (data) => this.onEventCallbackFunction(data),
...
}).build();
}
</script>
5. Use the link_id after a successful creation
Once the user connects successfully its bank account, the newly created link_id
is returned via callback to your client-side.
The link_id
can be used from the server-side to perform the following operations:
- retrieve accounts to get the account(s) details, including the current balance
- retrieve transactions to list all transactions on the account(s)
- retrieve owners to get the owner(s) details
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 or
- a new MFA token is needed.
For more information, check our guide to Update a link using the Connect widget.
Connect widget in Sandbox
For testing purposes, the Connect widget is also available in our Sandbox environment.
You need to have Sandbox API keys for that (check our dedicated guide if needed).
Once you have your Sandbox keys, you can follow the step by step process above including the following differences:
In step 1: Use the dashboard to add the domain you want to use to test the sandbox in the allowed URLs: https://dashboard.belvo.co/configuration/widget/
In step 2: Embed the Sandbox version of the widget in your head <script src="https://cdn.belvo.io/belvo-widget-1-stable.js"></script>
In step 3: Use the following URL to generate the access_token
: 'https://sandbox.belvo.co/api/token/'
Sandbox credentials
As soon as the Connect widget is started in the Sandbox environment, you can connect with our demo institutions and replicate different scenarios during the link creation.
Please, read our Sandbox section to see how it works and to get a full list of test credentials
Troubleshooting the Connect widget
While integrating, you may find some troubles like:
- the widget not opening
- the widget opening empty
- CORS errors displayed in the console
For any of those issues, check the following potential solutions:
- Allowed URL:
✅ Have you registered your URL (localhost or public URL) as an allowed URL to start the widget? It should be done in the configuration section of the dashboard. - Scope of access token:
✅ Are you specifying the scope of your access token when creating it? You can check the cURL example here."scopes": "read_institutions,write_links,read_links,delete_links"
- Access token generation:
✅ Are you generating your access token from your backend?
For security reasons, the token cannot be generated from the frontend.
If you need help, contact us at [email protected].
Updated 5 days ago
What's Next
Connect widget update mode |