Hosted Widget Branding and Customization (OFDA)

With Belvo's Hosted Widget, you can customize and brand the widget in two ways: through your access token request, and through the Custom Widget dashboard tool.

The settings below are sent as JSON in the same backend call as your request to generate an access_token. For a full example of how this looks, see the code example below.

You can add your company icon to the widget to make it more aligned with your brand. When you add your company icon, it appears on the following screen:

• initial start of the widget

Make sure that your icon has square dimensions, in SVG format, has a transparent background, and contains no surrounding whitespace. If your icon does not follow these specifications, the Belvo widget will display the following icon:

Instructions
To add a custom company icon, just add the URL to your SVG image to the company_icon key.

{
  "widget": {
    "branding": {
      ...
      "company_icon": "https://mysite.com/icon.svg",
      ...
        }
     }
}

You can add your company logo to the widget to make it more aligned with your brand. When you add your company logo, it appears on the following screens:

• while the account is being linked
• once an account is successfully linked
• when a user chooses to cancel the linking process

Make sure that your logo is in SVG format, has a transparent background, and contains no surrounding whitespace. For the best visibility and scaling, we suggest that you use a horizontal logo (see the top-left example in the image below).

Instructions
To add a custom company logo, just add the URL to your SVG image to the company_logo key.

{
  "widget": {
    "branding": {
      ...
      "company_logo": "https://mysite.com/logo.svg",
      ...
        }
     }
}

You can add your company name to be displayed when the widget first starts. By default, it'll just display "Link your account". When you add your company name, the message will follow the format "[company_name] uses Belvo to connect your account".

Instructions

To add your company name, just add it to the company_name key.

{
  "widget": {
    "branding": {
      ...
      "company_name": "ACME",
      ...
        }
     }
}

You can choose to display the Belvo logo between your company logo and the institution logo on the initial connect screen. This helps reinforce that Belvo is facilitating the secure connection. By default, this option is set to false, and only your company logo and the institution logo are displayed.

When enabled, the logo layout changes to: [Your Company Logo] → [Belvo Logo] → [Institution Logo]

Instructions

To display the Belvo logo in the middle of the initial connect screen, set the show_belvo_middle_logo parameter to true.

{
  "widget": {
    "branding": {
      ...
      "show_belvo_middle_logo": true,
      ...
    }
  }
}

You can modify the text describing the purpose for requesting your user's data (Propósito do compartilhamento) to better describe your use case.

By default, the displayed text is: _Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito. _

Instructions

To customize the text describing the purpose for requesting access to your user's data, just add your text (maximum 600 characters) to the purpose key.

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

You can specify the default consent duration (in days) that will be preselected in the consent screen dropdown. This helps streamline the user experience by presenting your preferred consent period as the default option.

The backend supports the following consent duration values:

How it works:

• If you provide one of the valid values (366, 275, 183, or 92), that option will be preselected in the consent duration dropdown.
• If you don't provide a value or provide a different value, "Indeterminado" (indefinite) will be the preselected option.
• The dropdown list order remains unchanged; only the preselected option changes.
• The widget accepts any positive integer, but only the values listed above correspond to the available consent duration options.

Instructions

To set the default consent duration, add the number of days to the default_consent_duration_days key within the consent object.

{
  "widget": {
    "consent": {
       "default_consent_duration_days": 183
    }
  }
}

You can choose to hide the "Mais de 5 milhões de usuários já conectaram com segurança suas contas." message that appears when your user selects their institution in the widget. By default, this message is visible in the widget (true).

Instructions

To hide the message in the institution select screen, just set the social_proof parameter to false.

{
  "widget": {
    "branding": {
      ...
      "social_proof": false,
      ...
        }
     }
}

CSS variables are configured visually through the Custom Widget tool in your Belvo dashboard.

Instructions

In your Belvo dashboard, go to Developer Tools > Custom Widget, and then in the Widget Configuration section set the:

1. Locale: the widget's display language: en (English), es (Spanish), or pt-BR (Portuguese).
2. Integration Type: Open Finance for the Brazil Open Finance (OFDA) widget, or Credentials for the multi-region widget.
3. Color scheme: Light or Dark. Dark-mode-specific CSS variables use a -dark suffix — for example, --color-primary-base-dark sets the primary color specifically for dark mode.
4. Country Codes: which countries' institutions appear in the widget preview.
5. Institution Types: which kinds of institutions appear in the preview: Fiscal (tax authority connections), Retail (personal banking), Business (corporate banking), or Employment (employer/payroll systems).

Once you've clicked Load Widget, you'll be able to access the CSS Variables panel. Search or use the category filters (Font, Navbar, Button, Banner, Input Text, and more) to find a variable, then enter a value. The Widget Preview on the right updates live as you type, so you can check each change before finalizing it.

Click Export Configuration. This automatically creates a Zendesk support ticket with your customization JSON attached, which the Belvo team uses to apply it to your account. Use Import to load a previously-exported configuration back into the tool if you want to keep editing it.

You can add a custom overlay color for when the widget loads in your desktop application. We recommend choosing a neutral color related to your brand to keep environmental context.

The loading screen shown while consent is being processed.