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. ```json { "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 } } ``` ```json { "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: ```json { "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"`: ```json { "widget": { "openfinance_feature": "consent_link_creation" } } ``` ## `callback_urls` In the `widget` object, you need to add the `callback_urls` object with the following information: ```json { "widget": { "callback_urls": { "success": "your-deeplink-here://success", "exit": "your-deeplink-here://exit", "event": "your-deeplink-here://error" } } } ``` ```json { "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: ```json { "consent": { "terms_and_conditions_url": "https://www.belvo.com" } } ``` ## `permissions` In the new `consent` object, we send through a default list of resources used to retrieve for the user using the `permissions` parameter. > 🚧 Changing Consent Permissions If you need to change the default consent permissions, please make sure to reach out to our [support team](https://support.belvo.com/hc/en-us/requests/new). ## `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). ```json { "consent": { "identification_info": [ { "type": "CPF", "number": "76109277673", "name": "Ralph Bragg" } ] } } ``` ```json { "consent": { "identification_info": [ { "type": "CPF", "number": "76109277673", "name": "Ralph Bragg" }, { "type": "CNPJ", "number": "50685362006773", "name": "Belvo OF test" } ] } } ``` # Additional configuration parameters (Hosted vs Web SDK ) Belvo offers two versions of the widget: - **Hosted (Recommended)** The Hosted 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 SDK** 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) ```Text 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](/developer_resources/web-widget-for-web#start-the-connect-widget): - `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. ```javascript // Code to be included within your