Introdução
O que é PIX Bacen?
A API PIX Bacen é uma versão da API Gateways 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 à API padrão Gateways para as operações listadas abaixo (cobrança, transferência por chave, devolução e saldo). As duas usam a mesma URL base (https://<api-host>/api), a mesma autenticação e as mesmas regras de negócio; mudam os formatos de requisição e resposta.
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
Com a versão de payload V2 (escolhida por webhook), as notificações usam o 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
Todos os endpoints ficam sob a URL base https://<api-host>/api, sem prefixo adicional:
| Endpoint | Método | Descrição |
|---|---|---|
/api/cob/:txid | PUT | Criar cobrança imediata (QR Code PIX) |
/api/pix/:e2eid/devolucao/:id | PUT | Solicitar devolução de um PIX recebido |
/api/dict/pix | POST | Iniciar transferência PIX (Cash-Out) |
/api/accounts/balances | GET | Consultar saldo da conta |
Comparação com API padrão
| Operação | API Padrão | API PIX Bacen |
|---|---|---|
| Cash-In | POST /api/pix/cash-in | PUT /api/cob/:txid |
| Cash-Out | POST /api/pix/cash-out | POST /api/dict/pix |
| Refund | POST /api/pix/refund-in/:id | PUT /api/pix/:e2eid/devolucao/:id |
| Balance | GET /api/balance | GET /api/accounts/balances |
Fluxo de integração
sequenceDiagram
participant Cliente
participant API as Gateways
participant BACEN
Note over Cliente,BACEN: 1. Autenticação
Cliente->>API: POST /api/auth/token
API-->>Cliente: access_token
Note over Cliente,BACEN: 2. Criar Cobrança
Cliente->>API: PUT /api/cob/\{txid\}
API->>BACEN: Registra cobrança
API-->>Cliente: QR Code + dados
Note over Cliente,BACEN: 3. Pagamento (via app bancário)
BACEN->>API: Webhook pagamento
API->>Cliente: Webhook V2 (type: RECEIVE)