In this section, you will 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_tokenusing your private API keys - Belvo returns a valid
access_tokento your server-side - The server returns the
access_tokento 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_idvia 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_idand 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
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")
Do not add the "/" at the end of the URL
You do not need to add the "/" at the end of your allowed URL for the widget. Adding it may result in the widget not working properly.
This is an example of valid URL:
https://www.acme-corp.com/home
This URL will not be valid:https://www.acme-corp.com/home/
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>
<!-- Sandbox version: <script src="https://cdn.belvo.io/belvo-widget-sandbox-1-stable.js"></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.
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"
}' \
-u [Secret Key ID]:[Secret Key PASSWORD]
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
scopesparameter 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 10 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: By default, the widget is started to create |
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 in Sandbox
For testing purposes, the Connect widget is also available in our Sandbox environment.
You will 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 your domain to 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-sandbox-1-stable.js"></script>
In step 3: Use the following URL to generate the access_token: 'https://sandbox.belvo.co/api/token/'
As soon as the Connect widget is started in the Sandbox environment, you can use any credentials to link an account in the widget. You can also use invalid as a username with any institution to test the login errors within the widget.
Updated 2 days ago