🚧

This articles refers to the multi-region widget

The content of this article refers to the multi-region widget (applicable for Colombia and Mexico). If you wish to operate in Brazil, please see our Connect Widget for Regulated OFDA.

For mobile-native applications, we've created a hosted version of our widget that significantly simplifies your development and integration process. All it requires is for you to create a webview in your application and some knowledge of handling deeplink redirects.

On this page, we'll provide you with reference documentation on what information to pass when starting your hosted widget as well as the possible events you can receive from the widget.

In this guide we’ll walk you through:

1. Generating an access token
2. Starting the hosted widget
3. Handling callback events
4. Retrieving data

1. Generating an access_token (Multi-Region)

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 keys: access and refresh. Pass the value of the access key when starting the hosted widget.

🚧

The returned values are valid for 10 minutes and we invalidate the token as soon as a user successfully connects their account.

To generate an access_token, simply make a call from your server-side to Belvo:

curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -H 'Host: sandbox.belvo.com' \
  -d 'see example payloads below'

{
  "id": "SECRET_ID",
  "password": "SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"],
  "credentials_storage": "store",
  "stale_in": "300d",
  "widget": {
    "callback_urls": {
      "success": "your-deeplink-here://success",
      "exit": "your-deeplink-here://exit",
      "event": "your-deeplink-here://error"
    }
}

2. Starting the widget (Multi-Region)

When you initiate your webview, in order to start the widget correctly, you need to pass your access_token in the URL string.

You can also pass the configuration parameters, such as the language of the widget (locale), what kind of link you want to create (access_mode), or what institutions to display based on the resources you can extract from them (resources), in the URL.

https://widget.belvo.io/
	?access_token={access_code}
  &locale=es
  &institution_types=retail
  &institutions=ofbradesco_br_retail
  &country_codes=BR
  &access_mode=recurrent
  &external_id=HJLSI-897809
  &resources=OWNERS,ACCOUNTS
  &integration_type=openfinance

For a full list of parameters (along with implementation details), please see our widget Startup Configuration (Multi-Region) article.

3. Handling callback events

We make use of deep link redirects in order to pass information about what happens in the widget. The structure of our deep links is:

You'll need to be able to handle success, exit, and error events.

Success event

You'll receive a success event when your user has successfully connected their account to their institution using the widget. Being able to handle the success event is critical as it contains the link id of the user (required to later retrieve data from the Belvo API).

your-url-here://success
	?link=cb65f82c-dc93-4d3e-8270-9a27528397f5
	&institution=erebor_br_retail

Exit event

You'll receive an exit event when your end user exits the widget:

• before connecting their account.
• after they have selected an institution.
• due to an error.

last_encountered_error

The last_encountered_error query string is only sent if an error occurred. See the table below for a full list of possible error codes and their messages.

meta_data

The meta_data query string is sent whenever a user exits the widget. See the table below for a list of possible values.

your-url-here://exit
	?last_encountered_error_code=login_error
  	&last_encountered_error_message=Invalid%20credentials%20provided%20to%20login%20to%20the%20institution
	&meta_data_institution_name=amex_mx_retail
	&meta_data_step=abandon-survey

Error event

You'll receive an error event whenever an error occurs during the use of the widget.

See the table below for a list of possible error codes and their messages.

your-url-here://exit
	?error=ACCESS_TOKEN_NOT_VALID
	&error_message=The%20access%20token%20was%20not%20provided%20or%20is%20not%20valid

Warning event

You'll receive a warning event whenever a non-terminating event occurs during the use of the widget.

See the table below for a list of possible warning codes and their messages.

your-url-here://warning
	?warning=institution_disabled
  &warning_message=The%20institution%20is%20temporarily%20unavailable.

4. Retrieving 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)

Platform Guides

To aid your development, we've created guides on how to set up deep links and listen for events for the following platforms:

• iOS (Swift)
• Android (Kotlin)
• React Native