Belvo - Developer Hub

Connect to any financial institution in Latin America with Belvo.

Build fintech innovations on top of any banking, fiscal and gig institutions in Latam.


Get started

Connect Widget

Suggest Edits

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:

❗️

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

company_name
String

You can pass your company or application name to customize the message displayed in the first screen:
"Vincula tu cuenta a [company_name]".

By default, without any company_name, the message will be "Vincula tu cuenta".

institution
String

If you want to start the widget directly on a specific institution credential screen, you can pass an institution as a parameter.

Example: institution: 'banamex_mx_retail'

By default, without any institution given, the widget is started on the list of institutions.

institution_types
Array

You can filter the type of institutions you want to see in the list using the institution_types parameter.
Example: institution_types: ['retail'] or institution_types: ['fiscal'] or institution_types: ['retail', 'business', 'fiscal', 'gig']

By default, the widget is started with all types of institutions supported by Belvo.

country_codes
Array

You can filter the countries you want to see in the list of institutions using the country_codes parameter. Only the institutions of the specified country(ies) will be displayed. Also, the countries will be displayed in the order specified in the country_codes parameter (country_codes: ['MX', 'CO'] will result in MX institutions first and CO ones after).

Example: country_codes: ['MX'] or country_codes: ['CO'] or country_codes: ['BR'] or country_codes: ['MX', 'CO'] or country_codes: ['CO','MX'] or country_codes: ['MX', 'CO', 'BR']

By default, the widget is started with all countries supported by Belvo.

locale
String

You can define the locale to be used by the widget.
Available options are 'es', 'en' and 'pt'

Example: locale: "en" or locale: "es" or
locale: "pt".

By default, the widget is started with 'es' as locale

access_mode
String

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: access_mode: "recurrent" or access_mode: "single".

Default access_mode will be the one defined in our API

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

link
String

The link_id created in the widget

institution
String

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

last_encountered_error
Object

A nullable object that contains the code and message of the error that was last encountered by the user. If no error was encountered, error will be null.
These are the possible error codes and messages you can receive:

  • login_error: Invalid credentials provided to login to the institution
  • unexpected_error: Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution
  • institution_down: The financial institution is down, try again later
  • too_many_sessions: Impossible to login, a session is already opened with the institution for these credentials
  • login_error: The user account is locked, user needs to contact the institution to unlock it
  • login_error: The user account access was forbidden by the institution
  • login_error: Impossible to login, something unexpected happen while logging into the institution. Try again later.
  • duplicated: Link already exists.

meta_data
Object

An object containing information about the institution selected by the user and the step at which the user exited the widget.
step may be one of the following values:

  • institutions: user prompted to select an institution
  • credentials: user prompted to input credentials
  • connection: connection was actually in progress

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

eventName
String

A string representing the name of event that has just occurred in the widget.
eventName may be one of the following values:

  • ERROR: when a recoverable error occurred in the widget, see the error_code and error_message in the meta_data

meta_data
Object

An object containing more information about the event that has just occurred in the widget.
The meta_data object can have the following properties:

  • error_code: The error code that the user encountered (see onExit() for the list of possible error codes)
  • error_message: The error message that the user encountered (see onExit() for the list of possible error messages)
  • institution_name: The selected institution
  • timestamp: A timestamp of when the event occurred

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:

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:

  1. 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.
  2. 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"
  3. 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

Connect Widget

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.