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