Connect to all finance institutions in Latin America

Welcome to Belvo's API

Belvo is an open banking and fiscal API for Latin America helping innovative companies to access banking and fiscal information in a secure and agile way.
To get up and running right away, follow our quick start guide.


Get started › Create account ›

Connect widget

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.

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

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:

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.0.11.js></script>
  ...
<head>
<body>
  ...
  <div id="belvo"></div> <!-- anywhere inside the body -->
  ...
<body>

3. Generate an access_token

Next, you need to generate an access_token from your server-side.
To protect you API keys (secretId and secretPassword), this token MUST be generated from your server-side.

Here is a Python example to generate this access_token:

secretId = "YOUR_SECRET_ID"
secretPassword = "YOUR_SECRET_PASSWORD"  
url = 'https://api.belvo.co/api/token/'
r = requests.post(url, verify=False, auth=HTTPBasicAuth(secretId, secretPassword), json={"id": secretId,"password": secretPassword,"scopes": "read_institutions,write_links,read_links,delete_links"})
access_token = r.json()['access']

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 successCallbackFunction (link_id) {
   // Do something with the link_id
  }
  
  function openBelvoWidget() {
    // call the server to generate an access token to start the widget
    // for example: 
    // access_token = getAccessTokenFromServer();
    belvoSDK.createWidget(access_token, {
      locale: 'es', // 'en' for English
      callback: (link) => this.successCallbackFunction(link)
    }).build();
  }

  document.getElementById("myIdToBeReplaced").onclick(openBelvoWidget());
       
</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 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 Sandbox dashboard to add your domain to the allowed URLs: https://sandbox.belvo.co/admin/users/allowedurl/
In step 2: Embed the Sandbox version of the widget in your head <script src=https://cdn.belvo.io/belvo-widget-sandbox-1.0.11.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 7 days ago

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.