With Belvo's Connect Widget, you can optionally add the following branding and customization:

• your company logo
• your company icon
• your company name
• link to your privacy policy
• text to highlight the benefits of your product
• text when a user chooses to close the widget
• hide messaging in account connect screen
• add a custom overlay color
• declare credential storage policy
• declare historical data retrieval
• declare resources for historical data retrieval

Full branding example

🚧

Add branding when generating access_token

To add branding to your widget, it must be done in the same server-side call as your request to generate an access_token. For a full example of how this looks like, see the code samples below.

curl -X POST \
  https://sandbox.belvo.co/api/token/ \
  -H 'Content-Type: application/json' \
  -H 'Host: sandbox.belvo.com' \
  -d '{
    "id": "SECRET_ID",
    "password": "SECRET_PASSWORD",
    "scopes": "read_institutions,write_links",
    "credentials_storage": "27d",
    "fetch_historical": true, 
  	"fetch_resources":  ["ACCOUNTS","TRANSACTIONS","OWNERS"],
    "widget": {
        "branding": {
        	"company_icon": "https://mysite.com/icon.svg",
            "company_logo": "https://mysite.com/logo.svg",
            "company_name": "ACME",
            "social_proof": true,
            "company_terms_url": "https://belvo.com/terms-service/",
            "company_benefit_header": "Faster approvals",
            "company_benefit_content": "Using Belvo cuts down on your loan approval time by up to 15 days.",
            "opportunity_loss": "It can take up to 20 days to evaluate your request using traditional methods.",
            "overlay_background_color": "#F0F2F4"
        }
     }
  }'

For more detailed information on each customization, see the relevant section below.

Add a company icon

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",
      ...
        }
     }
}

Add a company logo

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",
      ...
        }
     }
}

Add your company name

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

📘

Please note, only the company name is customizable in the introductory sentence.

Instructions

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

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

Add a link to your privacy policy

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/",
      ...
        }
     }
}

Add text to the connect screen

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.

🚧

You must provide content for both company_benefit_header and company_benefit_content. If you don't provide content for both, nothing will appear.

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

Add an exit message

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.",
      ...
        }
     }
}

Hide messaging in account connect screen

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,
      ...
        }
     }
}

Add a custom overlay color

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. By default, this overlay is set to grey.

📘

Overlay opacity

No matter what color you upload, Belvo will automatically set the opacity to 90%. This is due to the following UX best practices:

• With lower opacities (less than 70%), the user can experience difficulties focusing on the flow as they will have “visual noise” in the background.

• Block colors (opacity set at 100%) may cause a drastic change, resulting in a disjointed or unnatural experience.

Instructions

To set the overlay color, just add the full HEX code (# followed by six characters) to the overlay_background_color key.

{
  "widget": {
    "branding": {
      ...
      "overlay_background_color": "#F0F2F4",
      ...
        }
     }
}

Declare credential storage policy

You can set for how long Belvo is allowed to store the encrypted user credentials. Depending on your requirements, you can choose from the following values:

• store to store credentials (This is the default mode and Belvo stores credentials until the link is deleted).
• nostore to not store credentials.
• Any value between 1d and 365d to indicate the number of days you want the credentials to be stored.

📘

For links where access_mode=recurrent, this must be set to store

Instructions

To set the credential storage policy, just add the credentials_storage parameter with your value:

{
  "id": "SECRET_ID",
  "password": "SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "credentials_storage": "27d", // Add your credentials storage policy here
}

Declare historical data retrieval

If you are creating single links, you indicate whether you want Belvo to automatically perform a historical data retrieval for the user. When you set this to true, Belvo will retrieve all the information for the user and inform you via webhook that the information is ready for you to retrieve. For more information, see our Asynchronous historical data workflow (single links) documentation.

📘

When you use fetch_historical for single links, you must have webhooks set up as well as send through the fetch_resources parameter.

Instructions

To declare that you want to receive historical information for a single link, just add the fetch_historical parameter and set it to true.

{
  "id": "SECRET_ID",
  "password": "SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "fetch_historical": true, // Set this parameter to true
  "fetch_resources": [] // This parameter must also be sent through. See the section below
}

Declare resources for historical data retrieval

If you have set fetch_historical to true for single links, you must also indicate for which resources you want Belvo to historically retrieve information. For more information, see our Asynchronous historical data workflow (single links) documentation.

📘

To use fetch_resources for single links, you must have webhooks set up as well as set the fetch_historical parameter to true.

For banking institutions, you can select the following resources:
- ACCOUNTS
- OWNERS
- TRANSACTIONS
- INVESTMENTS_PORTFOLIOS
- RECEIVABLE_TRANSACTIONS

For fiscal institutions, you can select the following resources:
- INVOICES
- TAX_COMPLIANCE_STATUS
- TAX_DECLARATIONS
- TAX_RETENTIONS
- TAX_RETURNS
- TAX_STATUS

For employment institutions, you can select the following resources:
- OWNERS
- EMPLOYMENT_RECORDS

Instructions

To declare which resources you want to retrieve historical information for, just add the fetch_resources parameter and list the resources you want:

{
  "id": "SECRET_ID",
  "password": "SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "fetch_historical": true, // This parameter must be sent through and set to true
  "fetch_resources":  [ // list the resources you want to receive information for
    "ACCOUNTS",
    "TRANSACTIONS",
    "OWNERS"
  ]
}