OFDA widget token configuration

With OFDA Brazil, when you request your access_token you need to additionally send through these mandatory fields:

• scopes
• openfinance_feature
• callback_urls
• consent terms_and_conditions_url
• consent permissions
• consent identification_info

📘

Consent duration

According to Brazil's Open Finance regulations, our widget by default will always display the following consent durations that your users can choose from:

• 3 meses (three months)
• 6 meses (six months)
• 9 meses (nine months)
• 12 meses (twelve months)

Full OFDA access token example

{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
  "widget": {
    "openfinance_feature": "consent_link_creation",
    "callback_urls": {
      "success": "https://www.your-url-here.com/success",
    },
    "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"
        }
      ],
    }
  }
}

{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
  "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"
        }
      ],
    }
  }
}

Add the required scopes

With Open Finance Brazil, you need to send through additional scopes in the access_token request to be able to retrieve data from the user's institution.

These additional scopes are:

• read_consents
• write_consents
• write_consent_callback
• delete_consents

Instructions

To add the required scopes, just add "read_institutions,write_links,read_links,read_consents,write_consents,write_consent_callback,delete_consents" to the scopes key:

{
  "widget": {
    "scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents"
     }
}

Add the callback URLs

📘

If you're using Belvo's Widget for Web, you must the callback URLs that will redirect your user at the end of the flow.

You can add your own URLs where you want your users to be redirected after the widget flow is completed. You can set the following callback URLs:

• success - The URL your user is redirected to when the widget flow is successful.
• exit - The URL your user is redirected to when they exit the widget before completing the flow (only applicable when using Widget for Webviews).
• event - The URL your user is redirected to when they encounter an error (only applicable when using Widget for Webviews).

Instructions

To add the callback URLs, just add the callback_urls object with the success, exit, and event keys:

{
  "widget": {
    "callback_urls": {
      // The widget for web only supports a success callback URL.
      "success": "https://www.your-url-here.com/success",
    }
  }
}

{
  "widget": {
    "callback_urls": {
      "success": "your-deeplink-here://success", // Note: do not add https://www. or .com
      "exit": "your-deeplink-here://exit",
      "event": "your-deeplink-here://error"
    }
  }
}

🚧

If you are using Belvo's Widget for Webviews, make sure that you are able to process responses sent as deeplink query parameters. For example, with a success event, we will respond with your-deeplink-here://success?link={link_id}&institution={institution_name}.

Add the open finance mode

In the access_token request, you need to indicate whether you want your user to:

• Create a consent (and an associated link) in the open finance network.
• Create and manage their consent in the open finance network.

Instructions

To create a new consent, just add consent_link_creation to the openfinance_feature key:

{
  "widget": {
    "openfinance_feature": "consent_link_creation"
  }
}

To allow users to both manage their consent or create a new one, just add consent_management to the openfinance_feature key:

{
  "widget": {
    "openfinance_feature": "consent_management"
  }
}

To only allow users to manage their consent you will need to add an additional consent_management_link_creation key in the widget object and set it to false:

{
  "widget": {
    "openfinance_feature": "consent_management",
    "consent_management_link_creation": {
      "enabled": false
    }
  }
}

Add the consent terms and conditions

According to Open Finance Brazil, you need to send through the URL to your terms and conditions.

Instructions

To add the link to your terms and conditions, just add it to the terms_and_conditions_url key:

{
  "widget": {
    "consent": {
      "terms_and_conditions_url": "https://www.belvo.com"
    }
  }
}

Add the consent permissions

To be able to access access the owner, transaction, and account information of the user, you need to send through the following permissions:

• REGISTER
• ACCOUNTS
• CREDIT_CARDS
• CREDIT_OPERATIONS

Instructions

To request access to owner, transaction, and account information, just add ["REGISTER", "ACCOUNTS", "CREDIT_CARDS","CREDIT_OPERATIONS"] to the permissions key:

{
  "widget": {
    "consent": {
      "permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS","CREDIT_OPERATIONS"]
    }
  }
}

Add the consent identification information

You need to send through key identification information in your access_token request in order for the user to then be able to grant consent to their data.

• For individuals, you only need to provide one identification object (with the CPF).
• For businesses, you need to provide two identification objects (one containing the CPF information and another containing the CNPJ information).

{
  "widget": {
    "consent": {
      "identification_info": [
        {
          "type": "CPF",
          "number": "76109277673",
          "name": "Ralph Bragg"
        }
      ],
    }
  }
}

{
  "widget": {
    "consent": {
      "identification_info": [
        {
          "type": "CPF",
          "number": "37964623168",
          "name": "Lilian Silva"
        },
        {
          "type": "CNPJ",
          "number": "43053510000130",
          "name": "Lilian Psicologia Familiar"
        }
      ],
    }
  }
}