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 (OFDA)

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": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
  "credentials_storage": "365d",
  "stale_in": "300d",
  "fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"],
  "widget": {
    "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"
        }
      ]
    }
  }
}

{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
  "credentials_storage": "365d",
  "stale_in": "300d",
  "fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"],
  "widget": {
    "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.belvo.com",
      "permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"
      ],
      "identification_info": [
        {
          "type": "CPF",
          "number": "76109277673",
          "name": "Ralph Bragg"
        },
        {
          "type": "CNPJ",
          "number": "50685362006773",
          "name": "Belvo OF test"
        }
      ]
    }
  }
}

{
    "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjMzNDY1MDY5MiwiaWF0IjoxNzEyNTcwNjkyLCJqdGkiOiIxMDAxMTg4NDU4Y2M0ZTlhOThmMDA4MmU3MDU3YzBmNyIsInVzZXJfaWQiOiI2ZTliZTg4NC00NzgxLTQxNDMtYjY3My1hY2EwMjQ3NWVlOGMiLCJvcmdhbml6YXRpb25fbmFtZSI6IkRvbWluaWsgQ2hvbGV3c2tpJ3MgdGVhbSIsIm9yZ2FuaXphdGlvbl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsInNjb3BlcyI6WyJyZWFkX2luc3RpdHV0aW9ucyIsIndyaXRlX2xpbmtzIl0sImVudmlyb25tZW50Ijoic2FuZGJveCIsImFwaV91cmwiOiJzYW5kYm94LmJlbHZvLmNvbSIsImNyZWRlbnRpYWxzX3N0b3JhZ2UiOiIzMGQiLCJzdGFsZV9pbiI6IjM2NWQiLCJmZXRjaF9yZXNvdXJjZXMiOlsiQUNDT1VOVFMiLCJUUkFOU0FDVElPTlMiLCJPV05FUlMiXSwiaXNzIjoic2FuZGJveC5iZWx2by5jb20ifQ.X43VAc6c37U0JbiYgSd_r4SESjvGOuMgOpK5_DbuMHF7seATr7atO1QiUGwxdwBlEHo9ECST_9QKiHjv7G2czg",
    "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEyNTcxODkyLCJpYXQiOjE3MTI1NzA2OTIsImp0aSI6ImFiNjRmYjkyZmY1ZjQ0MTU4N2IwM2Y2MDJhMzhhMjNhIiwidXNlcl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsIm9yZ2FuaXphdGlvbl9uYW1lIjoiRG9taW5payBDaG9sZXdza2kncyB0ZWFtIiwib3JnYW5pemF0aW9uX2lkIjoiNmU5YmU4ODQtNDc4MS00MTQzLWI2NzMtYWNhMDI0NzVlZThjIiwic2NvcGVzIjpbInJlYWRfaW5zdGl0dXRpb25zIiwid3JpdGVfbGlua3MiXSwiZW52aXJvbm1lbnQiOiJzYW5kYm94IiwiYXBpX3VybCI6InNhbmRib3guYmVsdm8uY29tIiwiY3JlZGVudGlhbHNfc3RvcmFnZSI6IjMwZCIsInN0YWxlX2luIjoiMzY1ZCIsImZldGNoX3Jlc291cmNlcyI6WyJBQ0NPVU5UUyIsIlRSQU5TQUNUSU9OUyIsIk9XTkVSUyJdLCJpc3MiOiJzYW5kYm94LmJlbHZvLmNvbSJ9.2Irt1KCEKo6V17Y-N3zWeX3AchEvCrUWa_AlWoZ2gIIBhHvghHGkXtupOOrXKVqW9kTCOBE77-1riyyblUo4fw"
}

Configurable parameters

👍

Add additional branding to your widget

In addition to the required configurable parameter 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.

credentials_storage

You can set for how long Belvo is allowed to store the encrypted user credentials. Depending on your requirements, you can choose from the following values:

• store to store credentials (For links where access_mode=recurrent, this must be set to store).
• nostore to not store credentials.
• Any value between 1d and 365d to indicate the number of days you want the credentials to be stored.

📘

Default credential storage policies

For recurrent links, by default credentials_storage is set to store and cannot be changed.

For single links, by default credentials_storage is set to 365d.

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. By default Belvo stores user data for 365 days, unless the link is deleted.

📘

Belvo will only remove data for links that have not been updated in the period you provide in stale_in.

For example, if you set stale_in to 42d and only request information once on that day, then Belvo will remove any data associated with the link after 42 days. However, if you make another request five days later, then Belvo will restart the day counter to that day.

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.

📘

To use fetch_resources for single links, you must have webhooks set up.

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.

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"
      }
    ]
  }
}

{
  "consent": {
    "identification_info": [
      {
        "type": "CPF",
        "number": "76109277673",
        "name": "Ralph Bragg"
      },
      {
        "type": "CNPJ",
        "number": "50685362006773",
        "name": "Belvo OF test"
      }
    ]
  }
}

✳️ OK! Now that you can generate access_token, you can start the widget!

2. Starting the widget (OFDA)

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

3. 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.

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)