Introduction

What is PIX Bacen?

The PIX Bacen API is a version of the Forge 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 Forge 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 Forge
    participant BACEN

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

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

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