Hosted Widget Branding and Customization

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.

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 screens:

• 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 add a link to your privacy policy (or terms and conditions) on the initial screen of the widget that, when clicked, will redirect your users to the linked webpage. This helps your users better understand what your use case is regarding the data you are requesting. By default the widget will include the URL to Belvo's privacy policy (<https://belvo.com/terms-service/>).

Instructions
To add a link to your privacy policy in the initial connect screen, just add the URL to your policy to the company_terms_url key.

{
  "widget": {
    "branding": {
      "company_terms_url": "https://belvo.com/terms-service/",
        }
     }
}

When using a custom terms and conditions URL (via company_terms_url), you can track which version of your T&C the user accepted during the widget flow. This is useful for compliance and audit purposes, especially when your terms are updated over time.

Instructions
To track the T&C version, add the version identifier to the company_terms_version key. This parameter is required when you provide a custom company_terms_url (not using Belvo's default).

{
  "widget": {
    "branding": {
      "company_terms_url": "https://yourcompany.com/terms",
      "company_terms_version": "2024-03-15",
        }
     }
}

You can add a custom message on the initial screen of the widget to provide additional information to your users about why they need to connect their account using Belvo. This helps to drive conversion and increase end-user trust to link their account.

Instructions
To add custom text in the initial connect screen:

1. Add the title of the expand box to the company_benefit_header key.
   📝 The maximum length (including spaces) for the title is 30 characters.

2. Add the content for the expand box to the company_benefit_content key.
   📝 The maximum length (including spaces) for the content is 140 characters.

{
  "widget": {
    "branding": {
      "company_benefit_header": "Faster approvals",
      "company_benefit_content": "Using Belvo cuts down on your loan approval time by up to 15 days.",
        }
     }
}

You can add a custom message to be displayed when an end user chooses to cancel connecting their account. The message appears below a standard "Are you sure you want to cancel?" prompt. You can highlight the benefits of continuing to link their account using the widget in comparison to traditional methods.

Instructions

To add a custom exit message, add the content to display to the opportunity_loss key.

📝 Your message can have a maximum of 120 characters, including spaces.

{
  "widget": {
    "branding": {
      ...
      "opportunity_loss": "It can take up to 20 days to evaluate your request using traditional methods.",
      ...
        }
     }
}

You can choose to hide the "+1m users have securely connected their accounts using Belvo" message that appears when your user reaches the account connection screen in the widget. By default, this message is visible in the widget (true).

** Instructions**

To hide the message in the account connection 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.