INSTRUCTION NORMATIVE BCB NO. 306, OF SEPTEMBER 19, 2022

Regulatory document revoked, as of March 1, 2024, by Instruction Normative BCB No. 456, of February 29, 2024.

Publishes version 4.0 of the Open Finance API Manual.

The Heads of the Financial System Regulation Department (Denor) and the Information Technology Department (Deinf), in the exercise of the powers conferred upon them by arts. 23, item I, letter "a", and 62, item IV, of the Internal Regulations of the Central Bank of Brazil, annexed to Ordinance No. 84,287, of February 27, 2015, based on art. 3, item II, of Resolution BCB No. 32, of October 29, 2020,

R E S O L V E:

Art. 1 This Instruction Normative publishes version 4.0 of the Open Finance API Manual, mandatory observance by participating institutions, as per the Annex.

Sole Paragraph. The manual referred to in the caput, in its most recent version, will be accessible on the Open Finance page on the Central Bank of Brazil's website on the internet and on the Open Finance Portal in Brazil, maintained by the Structure Responsible for Open Finance Governance referred to in art. 44, § 1, of Joint Resolution No. 1, of May 4, 2020.

Art. 2 Instruction Normative No. 130, of July 22, 2021, is hereby revoked.

Art. 3 This Instruction Normative enters into force on October 1, 2022.

João André Calvino Marques Pereira Haroldo Jayme Martins Froes Cruz Head of the Regulation Department Head of the of the Financial System Information Technology Department

ANNEX TO INSTRUCTION NORMATIVE BCB NO. 306, OF SEPTEMBER 19, 2022

Open Finance API Manual Version 4.0

Revision History

Date	Version	Description of changes
19/9/2022	4.0	Improvements in the wording of the text, without alteration of merit.
Substitution of the expressions "Open Banking" by "Open Finance", as per the change promoted by Joint Resolution No. 4, of March 24, 2022, in Joint Resolution No. 1, of 2020.
Update of the Open Finance API table, considering phases 3 and 4 of Open Finance.
Improvement of the text regarding compatibility with the ISO 20022 standard.
Update of the "Versions" section.
Adjustments regarding traffic limits, operational limits, and API performance.
Inclusion of the "Transitional Provisions" section.

Terms of Use

This manual details the technical requirements for the implementation of the elements necessary for the operationalization of Open Finance, complementing the current regulation on the subject.

The manual will be reviewed and updated periodically in order to preserve compatibility with the regulation, as well as to incorporate improvements resulting from the evolution of Open Finance and technology.

More detailed information and examples of the application of this manual can be found in the guides and tutorials available on the Open Finance Portal in Brazil, in the Developer Area.

Suggestions, criticisms, or requests for clarification of doubts regarding the content of this document can be sent to the Central Bank of Brazil through the institutional channels of this autarchy.

References

The specifications of this manual are based on, reference, and complement, when applicable, the following documents:

Reference	Origin
Joint Resolution No. 1, of 2020	https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Resolu%C3%A7%C3%A3o%20Conjunta&numero=1
Resolution BCB No. 32, of 2020	https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Resolu%C3%A7%C3%A3o%20BCB&numero=32
Hypertext Transfer Protocol – HTTP/1.1	https://tools.ietf.org/html/rfc2616
ISO 20022	https://www.iso20022.org/
OpenAPI Specification	https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md
Representational State Transfer	https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

1. Introduction

Open Finance is intrinsically linked to the use of Application Programming Interface (API), interfaces through which it will be possible to interconnect the different systems of institutions. When made available by participants, the APIs must satisfy conditions such as standardization, robustness, and security, so that the sharing of data and services is carried out satisfactorily.

In this sense, this manual defines the main aspects related to the specifications and implementations of the APIs that integrate Open Finance in the Country, observing the provisions of Joint Resolution No. 1, of May 4, 2020, and Resolution BCB No. 32, of October 29, 2020.

Aspects such as: format for data exchange, interface design, protocol for data transmission, versioning, API model, and endpoints are treated in this manual. Thus, the manual establishes general guidelines without exhausting all aspects necessary for the implementation of APIs for Open Finance. The other definitions at the disposal of participating institutions through the structure responsible for governance, in accordance with Circular No. 4,032, of June 23, 2020, are available on the Open Finance Portal in Brazil, where guides, tutorials, and other operational information about APIs can be found.

Throughout this manual, the use of acronyms and specific terminology to designate some everyday expressions of technology professionals will be constant. Some examples of the most frequently used, with their corresponding definitions, are as follows:

I - API (Application Programming Interface): a set of definitions about how a system can access data or functionalities provided by another system;

II - REST (Representational State Transfer): architectural style of software;

III - RESTful API: API that adheres to the restrictions of the REST architectural style;

IV - OpenAPI: API specification language for RESTful APIs;

V - Endpoint: element of an OpenAPI specification on which operations can be executed to access data or functionalities;

VI - HTTP (Hypertext Transfer Protocol): protocol for hypertext, distributed, and collaborative systems; and

VII - Operation: element of an OpenAPI specification that declares a valid way to access an endpoint, informing, for example, which HTTP method (GET, POST, etc.) to use, names and types of parameters, etc.

2. Open Finance APIs

The table below displays the APIs that integrate Open Finance.

Type	Name	Description
Open Data	Products and Services	Must provide access to open data related to products and services offered by Open Finance participants.
Service Channels	Must provide access to open data related to public service channels offered by Open Finance participants.
Capitalization Titles	Must provide access to open data related to capitalization titles offered by Open Finance participants.
Investments	Must provide access to open data related to investment funds offered by Open Finance participants.
Foreign Exchange	Must provide access to open data related to foreign exchange offered by Open Finance participants.
Accreditation	Must provide access to open data related to accreditation offered by Open Finance participants.
Pension	Must provide access to open data related to pension offered by Open Finance participants.
Insurance	Must provide access to open data related to insurance offered by Open Finance participants.
Registration and Transactional Data	Consent	Must allow the creation, consultation, and revocation of access consents.
Resources	Must provide access to the list of resources consented by the client.
Registration Data	Must provide access to client registration data and their representatives.
Accounts	Must provide access to client transactional data related to checking accounts, savings accounts, and prepaid accounts.
Credit Card	Must provide access to client transactional data related to post-paid payment accounts.
Credit Operations - Advances to Depositors	Must provide access to client transactional data related to credit operations in the advance to depositors modality.
Credit Operations - Loans	Must provide access to client transactional data related to credit operations in the loan modality.
Credit Operations - Discounted Credit Rights	Must provide access to client transactional data related to credit operations in the discounted credit rights modality.
Credit Operations - Financing	Must provide access to client transactional data related to credit operations in the financing modality.
Services	Payment Initiation	Must allow the creation of payment consent, create payment initiation, and monitor the status of requests made.
Reports and Metrics	Environment Status	Must provide access to data on the current availability of API implementations, as well as data on scheduled unavailability.
Metrics	Must provide access to performance data of all APIs made available.

3. Principles

The principles below guide the specifications and implementations of Open Finance APIs.

3.1 User Experience

The specifications and implementations of APIs must offer a good experience for users, whether they are implementers or consumers of the APIs.

3.2 Technology Independence

API specifications must be technology-independent, being able to be implemented and consumed in different languages and/or platforms such as Java, JavaScript, Python, and Windows, Linux, Android, and iOS.

3.3 Security

Procedures and controls (digital signatures, encryption, authentication and authorization protocols, among others) must be adopted in a way to protect Open Finance participants, their clients, API consumers, and other participants in the ecosystem, observing compatibility with the institution's cybersecurity policy.

3.4 Extensibility

In the future, APIs may be improved to meet new use cases, and therefore, they must be specified and implemented in a way to allow and facilitate extensions such as, for example, new endpoints, operations, parameters, and properties.

3.5 Open Standards

Open standards must be adopted whenever possible.

3.6 RESTful APIs

API specifications must meet the restrictions of the REST architectural style whenever possible.

3.7 ISO 20022

API responses must be based on the elements and message components of ISO 20022 (https://www.iso20022.org/). Particular cases in which the adoption of the ISO standard is not possible or recommended may undergo adjustments, as long as they are specifically pointed out for evaluation by the Central Bank of Brazil.

3.8 Declaration of Obligation

All elements that make up the API specifications (endpoints, operations, parameters, response properties, etc.) must be explicitly declared as "Mandatory", "Optional", or "Conditional", if they are mandatory only under certain conditions.

Functionalities that are optional for the transmitter to implement must be explicit in their documentation, both to adequately inform the transmitting public, who may or may not implement the functionality, and to the consuming public, who may not find the functionality available in some transmitters.

4. Definitions and Recommendations

The definitions and recommendations below must be observed by the specifications and implementations of Open Finance APIs.

4.1 Specifications

APIs must be specified with version 3.0.0 or higher of the OpenAPI language (https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md).

API specifications must be analyzed with version 5.9.0 or higher of the free and open-source software Spectral (https://github.com/stoplightio/spectral/tree/v5.9.0). The analysis must be done with the standard ruleset of this version of Spectral. The result of the analysis must not contain errors or alerts.

It is recommended that version 3.0.25 or higher of the free and open-source software SwaggerCodegen (https://github.com/swagger-api/swagger-codegen/tree/v3.0.25) be used to generate client code and also the initial implementation code of APIs from their specifications. It is recommended that the generated code be analyzed with the aim of identifying possible features of the OpenAPI language that were used in the specifications, but that are not adequately supported by Swagger Codegen and, possibly, by other softwares that work with OpenAPI specifications. If this occurs, it should be evaluated whether it is not possible to alter the specifications to no longer use these resources.

Example implementations of APIs must be made available. The data returned by them do not need to be real data or voluminous, as the objective of making them available is to give the Central Bank of Brazil, implementers, and API consumers another resource to resolve any doubts regarding their specifications and implementations. It is recommended that the initial implementation code of APIs mentioned above be complemented in order to constitute the example implementations.

The information made available in the data dictionaries must be consistent with the associated OpenAPI specifications.

All endpoints of implemented APIs must be previously registered in the participant directory.

All registered endpoints that return lists, if the parameters are valid, must return the associated list, even if it is an empty list. A 404 error is not considered a valid return in this scenario, when there is no associated information.

4.2 Versions

The versions of API specifications will be classified as "major", "minor", "patch", and "release candidate" according to the following criteria:

I -major: includes new implementation features, changes, corrections to be incorporated, and which may be incompatible with previous versions, for example, v1.0.0 and v2.0.0;

II -minor: small changes in existing elements, with maintenance of compatibility with versions up to the immediately preceding major, for example, v1.1.0 and v1.2.0;

III -patch: clarifications to minor specifications, do not include functional changes, for example, v1.1.1, v1.1.2; and

IV -release candidate: pre-release versions of any future version of the patch, minor, or major type, for example, v1.0.0-rc and v1.0.0-rc2.

The Structure Responsible for Open Finance Governance, referred to in art. 44, § 1, of Joint Resolution No. 1, of 2020, may launch new versions of the APIs. The Central Bank of Brazil may define the implementation schedule for new major versions and the certification of participating institutions.

Finally, access credentials associated with APIs must be agnostic to their versions.

4.3 Open Finance Portal in Brazil

The website referred to in art. 15 of Resolution BCB No. 32, of 2020, must contain additional definitions and recommendations not present in this manual, as well as other artifacts necessary for the specification, implementation, and consumption of Open Finance APIs. All additional definitions and recommendations and artifacts published on the portal must be in agreement with this and with the other Open Finance manuals.

4.4 Schedule

The Open Finance Portal must list the APIs in production, their current versions, dates they entered production, link to their specifications, and list of changes since the last publication. It must also present the API homologation schedule, indicating version, date of publication, expected date of entry into production, and other relevant information.

4.5 Change Logs

All previously published versions of the APIs must be listed on the Open Finance Portal, along with their respective change logs and periods in which they were in production.

4.6 Additional Definitions

The Structure Responsible for Open Finance Governance must establish and publish on the Open Finance Portal an API specification style guide containing definitions and recommendations for the following elements:

I - URI Structure (Uniform Resource Identifiers);

II - HTTP Headers;

III - HTTP status Codes;

IV - Request and Response Body Conventions;

V - Naming Conventions;

VI - Common Data Types;

VII - Pagination; and

VIII - Identifier Stability.

4.7 Change Management Process

The Structure Responsible for Open Finance Governance must establish and publish on the Open Finance Portal the process it will adopt to manage changes in API specifications.

4.8 Tutorials

All information necessary for the development, testing, and production entry of applications or APIs in Open Finance must be available in tutorials published in the Developer Area on the Open Finance Portal. Each tutorial must contain all the necessary steps for the complete development of the activity in question, such as development and use of applications and APIs, authentication and authorization, use of the Sandbox, application of compliance tests, and registration in the directory. When pertinent, source code examples or screen captures must be provided, making the process as clear as possible for all participants and interested parties.

4.9 Extensibility

The specifications of Open Finance APIs may not provide access to all the data and functionalities that one or more participants wish to expose to API consumers. This may be necessary to better support use cases or enable innovations in financial products and services. To meet these and other needs, participants are permitted to implement extended versions of APIs entirely compatible with the standard API specifications, which are:

I - new endpoints;

II - new operations on pre-existing endpoints;

III - new parameters in pre-existing operations, as long as they are optional; and

IV - new properties in pre-existing responses.

The Structure Responsible for Open Finance Governance must publish on the Open Finance Portal the additional definitions and recommendations related to API extensions.

All extensions implemented by participants must be listed, with their referenced documentation, in a specific section on the Open Finance Portal and available for consumption, observing the expense reimbursement rules provided for in the current regulation.

5. Non-functional Requirements

This section presents the non-functional requirements that participating institutions must observe in the implementation of Open Finance APIs.

To assist in defining some non-functional requirements, it is necessary that each endpoint be classified on the Open Finance website according to its data update frequency, according to the options below:

I - High frequency;

II - Medium frequency; and

III - Low frequency

Traffic limits by source, operational limits, and response time (performance) will be defined based on this classification.

5.1 Traffic Limits

5.1.1 Limits by Source

Each endpoint implemented in Open Finance may have a restriction regarding traffic from a specific source. In 'open data' type APIs, the source is the IP from which the request originated, in authenticated APIs it is the IF/organizationId that made the request.

In the case of an institution implementing limits, they must respect the minimum values of Transactions Per Minute (TPM), as defined below:

I - 2,000 TPM, per endpoint and per source, in endpoints classified as high frequency;

II - 1,000 TPM, per endpoint and per source, in endpoints classified as medium frequency; and

III - 500 TPM, per endpoint and per source, in endpoints classified as low frequency.

Applicability: Some endpoints cannot have traffic limits defined by source, such as in Services type APIs, Security (Token – OAuth 2.0 consumption (FAPI), Token – DCR/DCM), Resources, and Consent APIs. The information defining whether the limit by source is 'applicable' or 'not applicable' must be explicit per endpoint on the Open Finance website.

Requests that exceed the implemented limits must be responded to with the HTTP status code 429 (Too Many Requests).

Finally, requests that exceed the limits must be disregarded in the calculation of the response time of API implementations.

5.1.2 Global Limits

The infrastructure of institutions providing APIs in Open Finance must have the capacity to, at a minimum, handle 300 simultaneous requests per second (TPS).

If the 300 TPS limit is reached, in the context of Open Finance, the institution must expand its infrastructure capacity to allow an increase of 150 TPS to the previous limit. Such an increase must occur again each time the limit current in the institution is reached. Each institution must create preventive monitoring, according to defined criteria; the evidence must be available to the Central Bank of Brazil for a period of twelve months.

Requests that exceed the TPS limits must be responded to with the HTTP status code 529 (Site is overloaded).

The Open Finance Portal must contain a detailed specification of how TPS and triggers for increasing or decreasing capacity will be calculated.

Endpoints created within the concept of extensibility, whether within new APIs or in existing APIs, cannot be considered for controlling the global limit of simultaneous transactions.

5.2 Operational Limits

Participating institutions are permitted to implement a monthly access limit per endpoint and per client.

In endpoints that access resources or products, the limits will also be considered per resource or product.

The counting of accesses must be performed by:

I - month;

II - endpoint;

III - most granular object referenced in the call (consent/resource/product);

IV - client (CPF or CNPJ); and

V - IF consuming the information.

---

For example: a receiving institution ‘A’ may access an endpoint ‘B’, accessing resource ‘C’, from a client “D” of the transmitting institution ‘E’, at least ‘N’ times (or calls) successfully per month.

Applicability of operational limits: all endpoints of the Data Cadastral and Transactional type APIs (according to Type classification), with the exception of those endpoints of the Consent (Consents) and Resource (Resources) APIs. APIs of the Open Data and Services types (such as Payment Initiation) cannot have operational limit restrictions.

The implementation of operational limits is optional for transmitting institutions, but once implemented, they must guarantee the minimum consumption established on the Open Financesite. The institution is permitted to expand these limits, but the implementation of limits lower than those established is prohibited.

The Open Financesite must list the minimum operational limit values to be considered, per endpoint, which must be equal to or greater than the following, according to the classification of usage frequency:

I - 4 calls per month, for endpoint classified as low frequency;

II - 30 calls per month, for endpoints classified as medium frequency;

III - 240 calls per month, for endpoint classified as high frequency; and

IV - 420 calls per month, for the following endpoints of the Accounts API: ‘Account Balances’ and ‘Account Limits’.

Only requests responded with an HTTP status code 2XX (success) shall be counted in the operational limits, and additional requests to an endpoint for pagination purposes shall not be counted.

Requests that exceed the operational limits shall be responded to with the HTTP status code 423.

All authenticated requests to endpoints subject to the operational limit must have the x-fapi-interaction-id attribute filled in its header by the receiver, which must be copied by the transmitter in the response headers. This definition aims to allow adequate tracking of discrepancies that may occur between transmitters and receivers associated with the operational limit.

5.3 Performance

The response time of each request must be measured, i.e., the time elapsed between the receipt of a request that does not exceed traffic limits and the moment the request is completely responded to. Additionally, this measurement must be made in such a way that the measured times are as close as possible to the response times experienced by the requester. In this context, the endpoints of the APIs must maintain the 95th percentile of response time at most:

I - 1,500ms, in endpoints classified as high frequency;

II - 2,000ms, in endpoints classified as medium frequency; and

III - 4,000ms, in endpoints classified as low frequency.

For example, on a day that a high-frequency endpoint receives 10,000 requests, the response time of at least 9,500 requests must be less than 1,500ms.

5.4 Availability

APIs classified as ‘Open Data’, ‘Data Cadastral and Transactional’, and ‘Reports and metrics’, listed in Section 2 of this manual, must satisfy the following minimum availability requirements. Each of its endpoints must be available:

I - 95% of the time every 24 hours; and

II - 99.5% of the time every 3 months.

APIs classified as ‘Services’ must have the same availability as the payment arrangement or service to which they are associated.

The Open Finance Portal must contain a detailed specification of how the availability of each endpoint will be calculated.

5.5 Timeout

Standardization of the server (server) response time timeout and the consumer (client) response time at fifteen seconds.

Requests that exceed the server timeout limit shall be responded to with the HTTP status code 504 (Gateway Timeout).

6. Transitional Provisions

The process of publishing version 2.0.1 of the ‘Data Cadastral and Transactional’ APIs in production, whose specification was launched on the Open Finance portal on 06/20/2022, must consider the following control points:

Date	Description
08/24/2022	Deadline for starting tests in the compliance engine
10/10/2022	Deadline for requesting functional certification of the APIs
10/31/2022	Deadline for certification and publication of the new APIs in the directory
02/23/2023	Last day of the deprecation period for version 1. Receiving institutions have until this date to migrate their solutions to the new version of the APIs. Transmitting institutions must discontinue the previous version only after this date.

The modifications to the quality requirements, updated in this manual, must be applied from the date of publication of the new APIs by the institutions.

Brasília, September 19, 2022.

NOTE 1135/2022-BCB/DENOR, OF SEPTEMBER 13, 2022.

Supports the proposal for the issuance of a normative instruction establishing version 4.0 of the Open Finance API Manual.

                        Gentlemen Heads of Denor and Deinf,

              This Note supports the proposal for the issuance of a normative instruction by the Financial System Regulation Department (Denor) and the Information Technology Department (Deinf), using the attribution granted to them by art. 23, item I, letter "a", of the Internal Regulations of the Central Bank of Brazil, annexed to Ordinance No. 84,287, of February 27, 2015, and observing item IX of art. 51 of Joint Resolution No. 1, of May 4, 2020.

2. Regarding this, the proposal deals with the issuance of a normative instruction establishing version 4.0 of the Open Finance API Manual, revoking Normative Instruction BCB No. 130, of July 22, 2021, which publishes version 3.0 of the Open Banking API Manual.

3.           The changes refer to the update of the expression Open Banking to Open Finance, according to changes made by Joint Resolution No. 4, of March 24, 2022, clarifications on the process of launching new APIs and their versions, and adequacy to the ISO 20022 standard; as well as technical adequacy in points concerning traffic and operational limits, API availability and performance, and standardization of response time *(time-out)*. The normative instruction proposal also provides for control points for the publication of version 2.0.1 of the ‘Data Cadastral and Transactional’ APIs, whose specification was launched on the *Open Finance* portal on June 20, 2022.
   

4.           Finally, in compliance with the provisions of art. 5º of Law No. 13,874, of September 20, 2019, Decree No. 10,411, of June 30, 2020, determines that proposals for normative acts of general interest for economic agents formulated by direct, autarchic, and foundation agencies of the federal public administration, as well as by collegiate bodies through the agency or entity responsible for providing them administrative support, must be preceded by a Regulatory Impact Analysis (RIA).
   

5.           However, it is worth highlighting that the proposed changes and adjustments do not cause significant impacts for the set of institutions participating in *Open Finance*, as they deal with clarifications and adaptations in guidelines already present in existing normative acts, such as the topic on versions, and adaptations related to traffic, limits, and call metrics with the aim of improving the information flow between the institutions participating in *Open Finance*, in order to enable their monitoring and clarify any disputes. In this sense, according to art. 4º, item III, of the aforementioned Decree, the normative act now proposed is exempt from the preparation of an RIA as it is considered low impact.
   
                     For your consideration.
   

Mardilson Fernandes Queiroz Aristides Andrade Cavalcante Neto Consultant of the Department Deputy Head of the Department of Financial System Regulation of Information Technology

                    In agreement.

João André Calvino Marques Pereira Haroldo Jayme Martins Froes Cruz Head of the Regulation Department Head of the Department of the Financial System of Information Technology