Widget for webviews
Fully responsive widget for mobile applications 📱.
Widget Overview
If you'd like to have a general overview of how the widget works, make sure to check out our Connect Widget Overview article.
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 webview as well as the possible events you can receive from the widget.
Widget for webviews and OFDA Brazil
When using the widget for webviews to create links with OFDA Brazil, make sure to set the following required parameters:
- set
locale
topt
- set
mode
towebapp
(Themode
query parameter is only used for OFDA brazil)Below is an example of all the query parameters:
https://widget.belvo.io/?access_token={access_code}&locale=pt&mode=webapp
Start Widget via webview
When you initiate your webview, in order to start the widget correctly, you need to pass your access_token
in the URL string.
Webview URL with access token
You can also pass the configuration parameters, such as the language of the widget and what institutions to display, in the call. For detailed information about these parameters, please see our widget Startup Configuration article.

Possible widget configuration parameters
https://widget.belvo.io/
?access_token={access_code}
&locale=es
&institution_types=retail
&country_codes=BR
&access_mode=recurrent
&external_id=HJLSI-897809
&resources=OWNERS,INVESTMENTS_PORTFOLIOS
&integration_type=openbanking
Widget responses
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 end user has successfully connected their account to their institution using the widget.

Success event structure
Parameter | Description |
---|---|
link | The link ID for the user. You'll need this ID to be able to make further requests for the user. |
institution | The institution that the link was created with. |
your-url-here://success
?link=cb65f82c-dc93-4d3e-8270-9a27528397f5
&institution=banamex_mx_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.

Exit event structure
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.
Error code | Error message |
---|---|
institution_down | The financial institution is down, try again later |
login_error | The possible error messages for a login_error are: - Invalid credentials provided to login to the institution - The user account is locked, user needs to contact the institution to unlock it - The user account access was forbidden by the institution - Impossible to login, something unexpected happened while logging into the institution. Try again later. |
too_many_sessions | Impossible to login, a session is already opened with the institution for these credentials |
unexpected_error | Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution |
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.
Parameter | Description |
---|---|
step | Sent when the user exits the widget at the initial screen. The value of the parameter is always abandon-survey . |
institution_name | Sent when the user exits the widget after selecting an institution. The value will be Belvo's institution code, for example banamex_mx_retail . |
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.

Error event structure
See the table below for a list of possible error codes and their messages.
Error code | Error message |
---|---|
ACCESS_TOKEN_NOT_VALID | The access token was not provided or is not valid |
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.

Warning event structure
See the table below for a list of possible warning codes and their messages.
Warning code | Warning message |
---|---|
institution_disabled | The institution is temporarily unavailable. |
your-url-here://warning
?warning=institution_disabled
&warning_message=The%20institution%20is%20temporarily%20unavailable.
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:
Updated 10 days ago