# Hosted Widget Overview (OFDA) ## Introduction For mobile-native and web-based 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. This page provides reference documentation on what information to pass when starting your hosted widget as well as the possible events you can receive from the widget. This guide walks you through: 1. Generating an access token 2. Starting the hosted widget 3. Handling callback events 4. Retrieving data For mobile-first applications, we've developed a specialized App2App flow that improves the user experience when they are connecting their account within your application. For more details, check out our Hosted Widget App2App Flow for OFDA. ## Generate an access token To display the widget to your end users, generate an `access` token on your server 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: ```shell curl -X POST \ https://sandbox.belvo.com/api/token/ \ -H 'Content-Type: application/json' \ -H 'Host: sandbox.belvo.com' \ -d 'see example payloads below' ``` Individual (OFDA) ```json { "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://event" }, "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" } ] } } } ``` Business (OFDA) ```json { "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://event" }, "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" } ] } } } ``` ```json Access Token Response Example { "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjMzNDY1MDY5MiwiaWF0IjoxNzEyNTcwNjkyLCJqdGkiOiIxMDAxMTg4NDU4Y2M0ZTlhOThmMDA4MmU3MDU...", "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEyNTcxODkyLCJpYXQiOjE3MTI1NzA2OTIsImp0aSI6ImFiNjRmYjkyZmY1ZjQ0MTU4N2IwM2Y2MDJhMzhh..." // [!code highlight] } ``` ### Configurable parameters In addition to the 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 To use `fetch_resources` for single or recurrent links, you must have enabled a webhook URL in the dashboard. For single and recurrent 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. | Resource | Institution Type | | --- | --- | | `ACCOUNTS` | Banking Brazil | | `OWNERS` | Banking Brazil | | `TRANSACTIONS` | Banking Brazil | | `BILLS` | Banking Brazil | | `INVESTMENTS` | Banking Brazil | | `INVESTMENT_TRANSACTIONS` | Banking Brazil | #### purpose In the `consent` object, you can customize the messaging that is displayed to your user regarding 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: ```json Consent Purpose { "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 `consent` object, we send through a default list of resources 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](https://support.belvo.com/hc/en-us/requests/new). #### 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: Individual (OFDA) ```json Individual (OFDA) Identification Info { "consent": { "identification_info": [ { "type": "CPF", "number": "76109277673", "name": "Ralph Bragg" } ] } } ``` Business (OFDA) ```json Business (OFDA) Identification Info { "consent": { "identification_info": [ { "type": "CPF", "number": "76109277673", "name": "Ralph Bragg" }, { "type": "CNPJ", "number": "50685362006773", "name": "Belvo OF test" } ] } } ``` OK! Now that you can generate an `access` token, you can start the widget! ## 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` For example: ```text Hosted Widget URL Example https://widget.belvo.io/?access_token={access_code}&locale=pt ``` 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: ```text Example Startup Query String https://widget.belvo.io/ ?access_token={access_code} &locale=pt &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: ```text Deeplink Structure Example your-url-here://event_name?parameters ``` | Parameter | Description | | --- | --- | | `your-url-here` | Your deeplink handler (scheme) | | `event_name` | The event name (host) | | `parameters` | The event parameters (sent as query strings) | ### 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). ```text Success Event Example your-url-here://success ?link={id}} &institution={institution_name} your-url-here://success ?link=cb65f82c-dc93-4d3e-8270-9a27528397f5 &institution=erebor_br_retail ``` | Parameter | Description | Example | | --- | --- | --- | | `link` | The link ID (UUID) for the user. You'll need this ID to be able to make further requests for the user. | `cb65f82c-dc93-4d3e-8270-9a27528397f5` | | `institution` | The institution that the link was created with. | `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. ```text Exit Event Example your-url-here://exit ?last_encountered_error_code={error_code} &last_encountered_error_message={error_message} &meta_data_institution_name={institution_name} &meta_data_step=abandon-{step_name} 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 ``` #### 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 | Example | | --- | --- | --- | | `step` | Sent when the user exits the widget at the initial screen. The value of the parameter is always `abandon-survey`. | `abandon-survey` | | `institution_name` | Sent when the user exits the widget after selecting an institution. The value will be Belvo's institution code | `ofmockbank_br_retail`. | ### Error event You'll receive an `error` event whenever an error occurs during the use of the widget. ```text Error Event Example your-url-here://error ?error={error_name} &error_message={error_message} your-url-here://error ?error=ACCESS_TOKEN_NOT_VALID &error_message=The%20access%20token%20was%20not%20provided%20or%20is%20not%20valid ``` See the table below for a list of possible error codes and their messages. | Error code | Error message (URL-Encoded) | | --- | --- | | `ACCESS_TOKEN_NOT_VALID` | The access token was not provided or is not valid | ### Warning event You'll receive a `warning` event whenever a non-terminating event occurs during the use of the widget. ```text Warning Event Example your-url-here://warning ?warning={warning_code} &warning_message={warning_message} your-url-here://warning ?warning=institution_disabled &warning_message=The%20institution%20is%20temporarily%20unavailable. ``` See the table below for a list of possible warning codes and their messages. | Warning code | Warning message (URL-Encoded) | | --- | --- | | `institution_disabled` | The institution is temporarily unavailable. | br Now that you can handle deep links and retrieve the link `id` from the `success` event, you can 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)