Introduction

What is PIX Bacen?

The PIX Bacen API is a version of the Fire Banking API that follows the official specification from the Central Bank of Brazil (BACEN) for the PIX instant payment system. This version was developed to serve integrators who need compatibility with the standard BACEN format.

This API is an alternative to the standard Fire Banking API. Both offer the same functionalities but with different request and response formats.

When should you use the PIX Bacen API?

Use this API when:

Your system is already integrated with other PSPs that follow the BACEN specification
You need to maintain compatibility with multiple PIX providers
Your application was built following the official Central Bank documentation
You prefer working with the V2 webhook format (envelope {type, data})

Key differences

Value Format

Monetary values are strings with 2 decimal places (e.g., "123.45") instead of numbers.

Webhook Structure

Webhooks use the envelope format {type, data} with status LIQUIDATED instead of CONFIRMED.

Identifiers

Uses txid for charges and e2eid for refunds, following BACEN naming conventions.

Separated Fields

Counterparty split into debtorAccount (payer) and creditorAccount (receiver).

Available endpoints

Endpoint	Method	Description
`/cob/:txid`	PUT	Create an immediate charge (PIX QR Code)
`/pix/:e2eid/devolucao/:id`	PUT	Request a refund for a received PIX
`/dict/pix`	POST	Initiate a PIX transfer (Cash-Out)
`/accounts/balances`	GET	Query account balance

Comparison with the standard API

Operation	Standard API	PIX Bacen API
Cash-In	`POST /pix/cash-in`	`PUT /cob/:txid`
Cash-Out	`POST /pix/cash-out`	`POST /dict/pix`
Refund	`POST /pix/:id/refund`	`PUT /pix/:e2eid/devolucao/:id`
Balance	`GET /balance`	`GET /accounts/balances`

Integration flow

sequenceDiagram
    participant Client
    participant Fire Banking
    participant BACEN

    Note over Client,BACEN: 1. Authentication
    Client->>Fire Banking: POST /oauth/token
    Fire Banking-->>Client: access_token

    Note over Client,BACEN: 2. Create Charge
    Client->>Fire Banking: PUT /cob/\{txid\}
    Fire Banking->>BACEN: Register charge
    Fire Banking-->>Client: QR Code + data

    Note over Client,BACEN: 3. Payment (via banking app)
    BACEN->>Fire Banking: Payment webhook
    Fire Banking->>Client: Webhook V2 (type: RECEIVE)