Open Finance Connectors

At Pluggy, apart from our usual Connectors, we now also support obtaining data from the Brazilian Open Finance Network with Open Finance Connectors.

Open Finance Connectors follow Pluggy's data model like any other Connector (Items, Accounts, Transactions, etc.), so there is no breaking change when obtaining data from Open Finance. However, they are some differences in the products they retrieve, the institutions they support and the way the user connects their account. In this guide we will discuss those differences so you can choose which connector type is best suited for your use case.

📘

Premium feature

If you are interested in using Open Finance Connectors, please contact our sales team to enable it for your plan

Products supported by Open Finance

Right now, Open Finance supports the following products:

• ACCOUNTS
• CREDIT_CARDS
• TRANSACTIONS
• IDENTITY
• LOANS
• INVESTMENTS

If your use case needs the INVESTMENTS product, for example, you can not retrieve this product with Open Finance Connectors at the moment.

Institutions supported by Open Finance

Here is a comparison of support of brazilian institutions from Open Finance and from normal connectors:

Investment Connectors that were not mentioned here, as well as other types like Digital Economy and Payment Processors are not currently supported by Open Finance, but have Normal Connectors available. Check out the Connectors Coverage docs for all our supported Connectors.

Connecting an Item with Open Finance

When a user connects through Open Finance, the login process is different from a normal connector.

First, the user is prompted for their CPF (for Personal connectors) or CNPJ:

Then, the user is taken to the institution's Open Finance login page (with a pop-up) to complete the login process:

This step depends on the institution: it can prompt the user to scan a QR, or offer a link that opens the institution's app directly, ask for credentials, etc.

After logging in, the user is prompted to select the information they will share:

After the user accepts to sharing that information, the pop-up is closed and they are taken back to the connection screen, while the connector finishes retrieving the data.

This flow is solved out of the box in Pluggy Connect. If you are not using Pluggy Connect, please refer to the guide at the bottom of this page.

Using Open Finance Connectors in my Application

Once you have Open Finance enabled for your plan, to add an Open Finance Connector, follow these steps:

Open Finance connectors will have an Open Finance tag, and appear as "[OF]" in the selected connectors list.

Now, users will be able to choose those institutions in Pluggy Connect (they look just like any usual connector):

Connecting an Item with Open Finance through API

Use this approach if you do not use Pluggy Connect and you want to connect using Pluggy's API. Once the Open Finance feature is enabled for your plan, follow these steps:

1. Obtain the connector ID for the Open Finance Connector of your choice. In the /connectors endpoint you will see them starting with ID 600 and higher. For example, Itaú's Open Finance Connector has ID 601.
2. Create an Item for that connector's ID. It will require CPF or CNPJ depending on if it's a Personal or Business connector.
3. Follow the Pluggy OAuth v2 documentation to complete the login. With this flow, from the created Item you will obtain a url to open for the user, which will transfer them to the institution's login.
4. Once the user completes the login, they are redirected to a Pluggy OAuth callback endpoint that starts the connection on the Item automatically.
5. Retrieve the data from the Item.

Open Finance Rate Limits

The Brazilian Open Finance Network imposes rate limits on how many times per month anyone using Open Finance can fetch each product. These limits apply per combination of CPF/CNPJ and institution:

Under normal usage of Open Finance Connectors (one CPF and institution on only one item), you usually won't have to worry about Rate Limits, since you would never reach them even if you had automatic updates enabled on all your items.

However, keep in mind that if you connect the same CPF/CNPJ to the same institution by creating multiple items, you can end up triggering a Rate Limit and affected products on those items will no longer update for that month.

When a rate limit is reached, you will see the Item in status PARTIAL_SUCCESS and inside the status detail, a warning about the failing product:

{
  "id": "44534b0e-717e-497d-890f-08c2faa468c1",
  "status": "PARTIAL_SUCCESS",
  "statusDetail": {
    "accounts": {
      "warnings": [
        {
          "code": "423",
          "message": "Open Finance monthly rate limit reached on product 'accounts' for this CPF/CNPJ and institution. The product could not be updated."
        }
      ],
      "isUpdated": false,
      "lastUpdatedAt": "2023-10-19T19:19:58.188Z"
    },
  },
  ...
}

Open Finance Test Account

To connect using our sandbox connection, you will be required to send as CPF the value "76109277673" and when accessing the Financial Institution of "Mock Bank" you can use the following parameters:

{
  user: "[email protected]",
  password: "P@ssword01"
}