bacen/pix-api: the OpenAPI specification behind Brazil's instant payment scheme

What bacen/pix-api actually is, and who it is for

The repository holds one specification artifact: openapi.yaml, an OpenAPI 3.0 document that defines the functional contract of the Pix API. Pix is the instant payment arrangement created by the Banco Central do Brasil, and this repository is the central bank's own publication of the interface that participants implement against. The README states the purpose plainly: the repository defines the functional specifications in OpenAPI 3.0 format for the Pix API.

The audience follows from that. If you work at a payment service provider, a bank, or a fintech that has to expose or consume Pix endpoints, this file is the contract you reconcile your implementation with. If you build developer tooling, mocks, or client SDKs for that ecosystem, it is the input format. The repository is not a library you import at runtime and not a server you deploy. Nothing in the README describes an executable component, which is the first thing to internalize: cloning this gives you a document, not a running API.

How the specification is organized and how changes reach you

The layout is deliberately small. The top-level entries are .github/, .gitignore, changelog.md, openapi.yaml and readme.md. There is no source tree, no build script, and no test directory. Everything substantive is in the single YAML file, and everything about evolution is in changelog.md plus the release tags.

The data flow is one-directional and manual. The maintainers edit openapi.yaml on master, tag a release, and the README points at the current release link. Consumers either download a tagged snapshot, reference the raw file at a specific commit, or generate code from it. The README also publishes a rendered view of the master branch at bacen.github.io/pix-api/index.html, which is convenient for reading but is not a versioned artifact. If you point your tooling at that rendered page or at master, you are tracking an unreleased state.

The release cadence visible in the tags is worth noting before you plan upgrades. 2.10.0 was tagged on 2026-08-19, 2.9.0 on 2025-09-05, and 2.8.2 on 2025-06-05. Two of those are about three months apart and one gap is roughly a year. A specification that governs a national payment scheme does not churn on a schedule you can predict from the tag list alone, so treat the changelog as the real upgrade signal rather than the version number.

Obtaining the Pix API specification and putting openapi.yaml to work

The README gives no install steps because there is nothing to install. What it does give is the location of the current release and the location of the raw specification. The README's OpenAPI validity badge links to the validator with the master copy of the file as its target, and that target URL is the one the project itself publishes:

https://raw.githubusercontent.com/bacen/pix-api/master/openapi.yaml

That URL is the file at master, which moves. If you want a fixed artifact, use a release tag in the same path shape, as the README does when it links to the 2.10.0 release page at github.com/bacen/pix-api/releases/tag/2.10.0. The README does not publish a tag-pinned raw URL, so confirm the tag exists before you depend on one.

Once you have openapi.yaml locally, the README offers no generator instructions, so any code generation step is your own choice of tooling rather than something this project prescribes. The repository also does not document a rollback procedure, a versioning policy beyond the tag list, or how to reconcile a generated client with a participant's actual behaviour. The rendered specification the README links is the master branch view:

https://bacen.github.io/pix-api/index.html

Read that page to understand the surface, but do not wire a build to it, because it reflects whatever is on master at the moment you load it. The file itself declares OpenAPI 3.0, which matters because generators and validators that only handle 3.1 or only handle Swagger 2.0 will not read it correctly. Check that your toolchain accepts a 3.0 document before you build anything on top of it.

The security gap is by design, and it is the main limitation

The README says it directly: the security aspects of the Pix API transcend the scope of this repository, and it redirects readers to the Manual de Padrões Para Iniciação do Pix and the Manual de Segurança do Pix on the BCB site. That is a clean boundary, and it is also the sharpest limitation for anyone who reads "API Pix" and expects a complete integration kit.

The practical consequence is that a team can generate a perfectly typed client from openapi.yaml and still be nowhere near production, because the parts that decide whether a request is accepted or rejected by a counterparty live in documents this repository does not contain. The same applies to certification requirements, which the README does not document at all. If your plan is "clone the spec, generate a client, ship," the missing middle is exactly the part that matters.

A second, softer limitation is that OpenAPI describes the functional surface, not the operational one. Rate limits, retry semantics, idempotency expectations under failure, and the behaviour of asynchronous flows are the sort of thing that a YAML file can gesture at but not settle. The README does not claim otherwise, and it does not attempt to. The honest reading is that this repository answers "what does the interface look like" and declines to answer "how do I operate against it safely."

How it compares with consuming a vendor's Pix API docs

The obvious alternative is not another tool of the same kind but a different source: the API documentation published by an individual Pix participant, or a commercial provider's SDK. The difference is one of authority and scope.

A participant's documentation describes one implementation of the scheme, including the parts that are specific to that participant, and it is written for people integrating with that participant. This repository describes the arrangement itself, from the body that defines it, and it is written for everyone implementing the scheme. If you are integrating with a single counterparty, their documentation will be more immediately useful, because it will cover the onboarding and security details this repository deliberately omits. If you are building something that has to work across participants, or you are generating tooling, the central specification is the reference that a vendor document is a specialization of.

The trade-off is real in both directions. Vendor docs give you a working path faster and a narrower one. The specification gives you the contract and leaves you to assemble the rest. Teams that need to move quickly against one partner should start with that partner's material and treat openapi.yaml as the cross-check; teams building shared infrastructure should invert that.

Maintenance, releases and the licence question

The repository is not archived, and the last push was on 2026-08-19, the same day 2.10.0 was tagged. That is recent enough that the project is being maintained, and the release history shows a steady if uneven rhythm: 2.8.2 in June 2025, 2.9.0 in September 2025, 2.10.0 in August 2026. The upgrade cost is therefore not in installing anything but in re-reading the changelog and re-diffing the YAML between the version you pinned and the version you are moving to. Because generated clients inherit every rename and every new field, an upgrade can ripple into your codebase even though you never compiled a dependency.

On licensing, the README carries an Apache 2.0 badge linking to the Apache licence text, which is the only licence information the repository surface provides. That is a permissive licence, but this is a specification document rather than a code library, and how a specification's licence interacts with generated artifacts and with your own implementation is a question for your legal team, not for this review. The README does not discuss licensing terms beyond the badge, so do not treat the badge as a full statement of what you may do with derived clients.

Editorial conclusion

Adopt bacen/pix-api if you are building a Pix participant integration, a mock, or a client generator and you need the functional contract straight from the source, pinned to a release tag rather than to master. Do not adopt it if you need security profiles, message signing, or certification rules: the README points those to the Manual de Padrões Para Iniciação do Pix and the Manual de Segurança do Pix, which live on the BCB site, not in this repository. Before you commit to a version, open changelog.md and diff the release you plan to pin against the one before it, because 2.10.0 and 2.9.0 are roughly a year apart and the contract will have moved.

Frequently asked questions

Official sources

1. bacen/pix-api on GitHub
2. Issues
3. Project website
4. README
5. Releases