Introdução

O que é PIX Bacen?

A API PIX Bacen é uma versão da API Forge que segue a especificação oficial do Banco Central do Brasil para o sistema de pagamentos instantâneos PIX. Esta versão foi desenvolvida para atender integradores que precisam de compatibilidade com o formato padrão BACEN.

Esta API é uma alternativa a API padrão Avista. Ambas oferecem as mesmas funcionalidades, mas com formatos de requisição e resposta diferentes.

Quando usar a API PIX Bacen?

Use esta API quando:

Seu sistema já está integrado com outros PSPs que seguem a especificação BACEN
Você precisa manter compatibilidade com múltiplos provedores PIX
Sua aplicação foi construída seguindo a documentação oficial do Banco Central
Você prefere trabalhar com o formato de webhook V2 (envelope {type, data})

Principais diferenças

Formato de Valores

Valores monetários são strings com 2 casas decimais (ex: "123.45") ao invés de números.

Estrutura de Webhook

Webhooks usam formato envelope {type, data} com status LIQUIDATED ao invés de CONFIRMED.

Identificadores

Usa txid para cobranças e e2eid para devoluções, seguindo nomenclatura BACEN.

Campos Separados

Contraparte dividida em debtorAccount (pagador) e creditorAccount (recebedor).

Endpoints disponíveis

Endpoint	Método	Descrição
`/cob/:txid`	PUT	Criar cobrança imediata (QR Code PIX)
`/pix/:e2eid/devolucao/:id`	PUT	Solicitar devolução de um PIX recebido
`/dict/pix`	POST	Iniciar transferência PIX (Cash-Out)
`/accounts/balances`	GET	Consultar saldo da conta

Comparação com API padrão

Operação	API Padrão	API PIX Bacen
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`

Fluxo de integração

sequenceDiagram
    participant Cliente
    participant Avista
    participant BACEN

    Note over Cliente,BACEN: 1. Autenticação
    Cliente->>Avista: POST /oauth/token
    Avista-->>Cliente: access_token

    Note over Cliente,BACEN: 2. Criar Cobrança
    Cliente->>Avista: PUT /cob/\{txid\}
    Avista->>BACEN: Registra cobrança
    Avista-->>Cliente: QR Code + dados

    Note over Cliente,BACEN: 3. Pagamento (via app bancário)
    BACEN->>Avista: Webhook pagamento
    Avista->>Cliente: Webhook V2 (type: RECEIVE)