Introducción
Que es PIX Bacen?
La API PIX Bacen es una versión de la API de Brasil Bitcoin que sigue la especificacion oficial del Banco Central de Brasil (BACEN) para el sistema de pagos instantaneos PIX. Esta versión fue desarrollada para atender a integradores que necesitan compatibilidad con el formato estandar del BACEN.
Esta API es una alternativa a la API estandar de Brasil Bitcoin. Ambas ofrecen las mismas funcionalidades pero con diferentes formatos de solicitud y respuesta.
Cuando deberia usar la API PIX Bacen?
Use esta API cuando:
- Su sistema ya esta integrado con otros PSPs que siguen la especificacion del BACEN
- Necesita mantener compatibilidad con multiples proveedores PIX
- Su aplicación fue construida siguiendo la documentación oficial del Banco Central
- Prefiere trabajar con el formato de webhook V2 (envelope
{type, data})
Diferencias clave
Formato de Valores
Los valores monetarios son strings con 2 decimales (ej., "123.45") en lugar de números.
Estructura de Webhooks
Los webhooks usan el formato de envelope {type, data} con estado LIQUIDATED en lugar de CONFIRMED.
Identificadores
Usa txid para cobros y e2eid para devoluciones, siguiendo las convenciones de nomenclatura del BACEN.
Campos Separados
La contraparte se divide en debtorAccount (pagador) y creditorAccount (receptor).
Endpoints disponibles
| Endpoint | Método | Descripción |
|---|---|---|
/cob/:txid | PUT | Crear un cobro inmediato (PIX QR Code) |
/pix/:e2eid/devolucao/:id | PUT | Solicitar una devolución de un PIX recibido |
/dict/pix | POST | Iniciar una transferencia PIX (Cash-Out) |
/accounts/balances | GET | Consultar saldo de la cuenta |
Comparacion con la API estandar
| Operación | API Estandar | API PIX Bacen |
|---|---|---|
| Cash-In | POST /pix/cash-in | PUT /cob/:txid |
| Cash-Out | POST /pix/cash-out | POST /dict/pix |
| Devolución | POST /pix/:id/refund | PUT /pix/:e2eid/devolucao/:id |
| Saldo | GET /balance | GET /accounts/balances |
Flujo de integración
sequenceDiagram
participant Client
participant Brasil Bitcoin
participant BACEN
Note over Client,BACEN: 1. Autenticación
Client->>Brasil Bitcoin: POST /oauth/token
Brasil Bitcoin-->>Client: access_token
Note over Client,BACEN: 2. Crear Cobro
Client->>Brasil Bitcoin: PUT /cob/\{txid\}
Brasil Bitcoin->>BACEN: Registrar cobro
Brasil Bitcoin-->>Client: QR Code + datos
Note over Client,BACEN: 3. Pago (via app bancaria)
BACEN->>Brasil Bitcoin: Webhook de pago
Brasil Bitcoin->>Client: Webhook V2 (type: RECEIVE)