Open Finance Data Aggregation Brazil (OFDA)

With Belvo's Open Finance Data Aggregation (OFDA) product for Brazil, you have access to Brazil's open finance network that provides standardized and improved data points.

In this section of the documentation, we'll provide you with information regarding what changes (and what doesn't), as well as a high-level overview of the new schema.

Standard (Multi-Region) vs OFDA schemas

We've introduced a new naming convention to differentiate between the data you can receive in the Belvo API.

• Standard (Multi-Region): This is the standard schema that is applicable for all countries and institutions.
• Open Finance Data Aggregation (OFDA): This is the expanded schema that is applicable solely to Brazilian institutions within the Open Finance network.

In our API reference, you can see the differences between the two schemas by clicking on the relevant schema:

No breaking changes

We have devoted a significant amount of effort to ensure that with the release of OFDA Brazil there will be no breaking changes with your integration. Our OFDA Brazil schema contains all the same fields as our Standard (Multi-Region) schema.

Which resources support the OFDA Brazil schema

OFDA Brazil currently only applies to Owners, Accounts, and Transactions. As the Open Finance network in Brazil grows, we'll be updating our API to provide the full functionality (in step with Brazil's developments).

How do I receive the OFDA Brazil schema

You'll receive the new schema whenever a user decides to connect their account using the Open Finance network.

For example:

• If your user selects the Caixa Open Finance institution and grants their consent to share their data, then the data you receive will be in the Open Finance Brazil format.
• If they choose the regular version of Caixa, you'll receive the Standard (Multi-Region) format of our schema.

📘

You can set up your widget to only display open finance institutions. For more information, see our Startup configuration article.

Widget for OFDA

With OFDA, there are two changes in Belvo's Connect Widget:

1. You need to provide additional information when requesting your access token. Please see our OFDA widget token configuration article for the details.
2. The user flow undergoes several changes:
   1. Users will see a Consent screen where they can review what information you are requesting to view as well as select the duration for which they want to share their information for.
   2. Users will be redirected to their institution to log in and grant consent.
   3. Once they grant consent, they are redirected back to the Belvo Connect Widget where they will see a summary of the information they are sharing with you.

📘

For OFDA, the Connect Widget is only available in Portuguese (Brazil).

Schema guides

As mentioned, in our API reference you can select which schema to view. However, we've also created high-level guides of the differences between the schemas in our guides for each of the affected resources:

• Owners
• Accounts
• Transactions

Example 1: New fields with mandatory data

In the example below, the addresses field is a new field in the Belvo schema and must return data. Within addresses you'll also see that only five fields must always be populated (is_main, address, town, postcode, and country). The rest of the fields may return null.

{
  "address": "Av Naburo Ykesaki, 1270 17500001 Brasilia",
  "addresses": [ // New and not-nullable
    {
      "is_main": true, // not-nullable
      "address": "Av Naburo Ykesaki, 1270", // not-nullable
      "additional_info": "In between two palm trees",
      "district_name": "CENTRO",
      "town": "Brasilia", // not-nullable
      "town_code": "3550308",
      "state": "SP",
      "postcode": "17500001", // not-nullable
      "country_name": "Brasil", // not-nullable
      "country_code": "BRA",
      "latitude": "-23.5475000",
      "longitude": "-46.6361100"
    }
  ]
}

Example 2: Conditionally mandatory data

In the example below, you'll see that patrimony is a new field in the Belvo schema. However, this field may return null if there is no data available in the institution.

If the institution does have patrimony data, then Open Finance must return data for amount, currency, and year.

{
  "patrimony": { // New and nullable
      "amount": 45391.89, // Not nullable when parent (patrimony) is returned
      "currency": "BRL", // Not nullable when parent (patrimony) is returned
      "year": 2020 // Not nullable when parent (patrimony) is returned
    }
}

{
  "patrimony": null,
}