Introducción
Que es PIX Bacen?
La API PIX Bacen es una versión de la API de LF Gateway 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 LF Gateway. 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 LF Gateway
participant BACEN
Note over Client,BACEN: 1. Autenticación
Client->>LF Gateway: POST /oauth/token
LF Gateway-->>Client: access_token
Note over Client,BACEN: 2. Crear Cobro
Client->>LF Gateway: PUT /cob/\{txid\}
LF Gateway->>BACEN: Registrar cobro
LF Gateway-->>Client: QR Code + datos
Note over Client,BACEN: 3. Pago (via app bancaria)
BACEN->>LF Gateway: Webhook de pago
LF Gateway->>Client: Webhook V2 (type: RECEIVE)