Guides
API StatusAPI ReferenceError DocsInstitutionsSupportSign inCreate a Sandbox account

Migrating to the Open Finance regulated widget

Suggest Edits

👍

The following documentation is aimed at organizations that currently use the non-regulated widget to retrieve data from Brazilian institutions and need to migrate to the regulated widget to access data from Brazil’s Open Finance network.

To access information from institutions in Brazil’s Open Finance network, your users need to use Belvo’s regulated widget to grant their consent for you to access their data.

📘

Regulated vs Non-Regulated

Regulated widget:
Allows users to grant their consent to access information from open-finance regulated institutions in Brazil.

The user starts in the widget, selects an institution and after configuring the consent duration and operations, the user is redirected to the institution itself to log in and accept the consent settings. Then the user is redirected to the hosted widget where the flow will end with the consent and link being created.

Non-Regulated widget:
Allows users to grant their consent to access information from non-regulated institutions (for example all institutions in Mexico as well as Brazil’s INSS ).

Your user remains in the widget the whole time until the link is created. The flow begins with the user selecting an institution, then entering their credentials in order to fetch the information from the institution, and finally being able to create the link.

In this guide, we focus on the changes you need to make in your current non-regulated widget to be able to create links and consents for users in Brazil’s regulated open finance network:

  1. Generating the access_token for the regulated widget flow.
  2. Additional configuration parameters (webview vs web)

Generating the regulated access_token

When generating the access_token for the regulated widget, you need to make several changes to your current configuration.

{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
  "fetch_resources": ["OWNERS", "ACCOUNTS", "TRANSACTIONS"], // Required for single links
  "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"
        },
        {
          // only for business
          "type": "CNPJ",
          "number": "50685362006773",
          "name": "Belvo OF test"
        }
      ]
    },
    "branding": {}, // optional
    "theme": [] // optional
  }
}


{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "fetch_resources": ["OWNERS", "ACCOUNTS", "TRANSACTIONS"], // Required for single links
  "widget": {
    "branding": {}, // optional
    "theme": [] // optional
  }
}

scopes

You need to update the scopes field to have just following permissions:

{
  "scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
}

openfinance_feature

In the widget object, you need to add "openfinance_feature": "consent_link_creation":

{
  "widget": {
    "openfinance_feature": "consent_link_creation"
  }
}

callback_urls

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

{
  "widget": {
    "callback_urls": {
      "success": "your-deeplink-here://success",
      "exit": "your-deeplink-here://exit",
      "event": "your-deeplink-here://error"
    }
  }
}

{
  "widget": {
    "callback_urls": {
      "success": "your-deeplink-here://success"
    }
  }
}

Webview

Where:

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

Web

Where:

  • success is the URL your user is redirected to when the flow is successful.

You do not need to provide the exit or event URLs for the Widget for Web as when you use the widget SDK these parameters are provided in the widget configuration.

terms_and_conditions_url

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

{
  "consent": {
    "terms_and_conditions_url": "https://www.belvo.com"
  }
}

permissions

In the new consent object, you need to add the following list of resources that you want to retrieve for the user using the permissions parameter:

{
  "consent": {
    "permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"]
  }
}

identification_info

In the new consent object, you need to add the following list of resources that you want to retrieve for the user using the permissions parameter:

In the new 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).

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

Additional configuration parameters (webview vs web)

Belvo offers two versions of the widget:

  • Webview (Recommended)
    The Webview widget is hosted by Belvo and does not require any javascript configuration. All the configurations are set using URL query parameters. The Webview widget can be used in both your web application or inside a webview in native applications.
  • Web
    The Web widget involves inserting a script in your page to embed the widget SDK inside your application without an iFrame. The configuration parameters for the widget are set using javascript. This Web widget can only used in your web application (and not inside a webview in native applications).

In this section we list the changes in the parameter configuration between non regulated institutions and regulated institutions.

Webview configuration

For the webview, the only required configurations to use the regulated widget are to set the following query parameters:

  • locale to pt (ensures that the widget displays in Brazilian Portuguese)
  • integration_type to openfinance (ensures that only Open Finance institutions are
  • access_token (the access_token you generated)
https://widget.belvo.io/
	?access_token={access_code}
  	&locale=pt
    &integration_type=openfinance

Web configuration

If you are using our web widget, you will need to make the following changes in the openBelvoWidget function:

  • integration_type: set this to openfinance to filter out the non-regulated institutions.
  • callback: remove this parameter as it is replaced by the success URL you provide during access token generation.
  • onExit: this parameter will only be used until the user is redirected to their institution, and as such, can be optional.
  • onEvent: this parameter will only be used until the user is redirected to their institution, and as such, can be optional.
// Code to be included within your <script type="text/javascript"> tag

function openBelvoWidget(accessToken) {
	belvoSDK.createWidget(accessToken, {
		integration_type: 'openfinance', // Add this field
		callback: (link, institution) => successCallbackFunction(link, institution), // Remove parameter
		onEvent: (data) => this.onEventCallbackFunction(data), // optional
	  onExit: (data) => this.onExitCallbackFunction(data) // optional
	}).build();
}

getAccessToken().then(openBelvoWidget) // Once the access token is retrieved, the widget is started.

Recommendations

For regulated institutions, we highly recommend you use the Widget for Webviews as this minimizes your development complexity.

If you use the Widget for Web (inserting a javascript snippet in your application), after your user grants their consent in their institution they will be redirected to the Webview Widget (and not to the Web version of the widget). This requires additional development on your side as:

  • some Web parameters are used just in the first part of the flow (for example, onEvent and onExit).
  • you still need to configure the hosted widget parameters for the final step in the flow.

Updated 1 day ago