Hosted Widget Overview (OFDA)

Introduction

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

Generate an access token

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.

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": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
  "stale_in": "300d",
  "fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"],
  "widget": {
    "purpose": "Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito.",
    "openfinance_feature": "consent_link_creation",
    "callback_urls": {
      "success": "your_deeplink_here://success",
      "exit": "your_deeplink_here://exit",
      "event": "your_deeplink_here://error"
    },
    "consent": {
      "terms_and_conditions_url": "https://www.your_terms_and_conditions.com",
      "permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"],
      "identification_info": [
        {
          "type": "CPF",
          "number": "76109277673",
          "name": "Ralph Bragg"
        }
      ]
    }
  }
}

{
    "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjMzNDY1MDY5MiwiaWF0IjoxNzEyNTcwNjkyLCJqdGkiOiIxMDAxMTg4NDU4Y2M0ZTlhOThmMDA4MmU3MDU...",
    "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEyNTcxODkyLCJpYXQiOjE3MTI1NzA2OTIsImp0aSI6ImFiNjRmYjkyZmY1ZjQ0MTU4N2IwM2Y2MDJhMzhh..."
}

Configurable parameters

In addition to the required configurable parameters below, you can also add additional branding and customization to your widget when generating your access token. For more information, see our dedicated Branding and customization (OFDA) guide.

stale_in

You can indicate how long any data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through 90d, Belvo will remove any data from its database relating to the user after 90 days (that is, 90 days after the last time the information was retrieved for the user). By default Belvo stores user data for 365 days, unless the link is deleted.

fetch_resources

For single links, you can set which resources Belvo will asynchronously retrieve historical information for using the fetch_resources parameter. For more information, see our Asynchronous historical data workflow (single links) documentation.

purpose

In the consent object, you can customize the messaging that is displayed to your user regarding for what use case you are requesting their data for in the purpose field. By default, the widget displays the following message: _Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito. _.

To change the content, just add your text (maximum 600 characters) to the purpose field:

{
  "widget": {
    "consent": {
       "purpose": "Your custom text here. Max 600 characters",
       ...
    }
  }   
}

callback_urls

In the widget object, you need to add the callback_urls object with the following information:

• success is the deeplink URL your user is redirected to when the flow is successful.
• exit is the deeplink URL your user is redirected to when they exit the widget before completing the flow.
• event is the deeplink URL your user is redirected to when an error occurs.

terms_and_conditions_url

In the consent object, you need to add a link to the terms and conditions of your company using the terms_and_conditions_url parameter.

permissions

In the new consent object, we send through a default list of resources used to retrieve for the user using the permissions parameter. The value of the permissions must always be the following array of items: ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"].

🚧 Changing Consent Permissions

If you need to change the default consent permissions, please make sure to reach out to our support team.

identification_info

In the consent object, you need to provide the identification information of the user that you want to retrieve information for in the identification_info parameter. The information that you provide here must match the information that the regulated institution has for the user (for example, for businesses, the CPF and name must be for a user with access to the business account). For example:

{
  "consent": {
    "identification_info": [
      {
        "type": "CPF",
        "number": "76109277673",
        "name": "Ralph Bragg"
      }
    ]
  }
}

Start the Widget

When you initiate your hosted widget, in the URL string you need to pass your:

• generated access token
• set locale to pt
• set mode to webapp

For example:

https://widget.belvo.io/?access_token={access_code}&locale=pt&mode=webapp

You can also pass additional configuration parameters, such as 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. For a full list of parameters (along with implementation details), please see our widget Startup Configuration (OFDA) article. For example:

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

Handling callback events

The hosted widget makes use of deep link redirects to pass information about what happens in the widget. You'll need to be able to handle success, exit, and error events. The structure of the deep link is:

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

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.

Now that you can handle deep links (most importantly to retrieve the link id from the success event), you will be able to start retrieving data about your user.

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)