Introducción
Que es PIX Bacen?
La API PIX Bacen es una versión de la API de FyPay 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 estándar de FyPay para las operaciones listadas abajo (cobro, transferencia por clave, devolución y saldo). Ambas usan la misma URL base (https://api.fypay.me/api), la misma autenticación y las mismas reglas de negocio; solo cambian los 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
Con la versión de payload V2 (elegida por webhook), las notificaciones 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
Todos los endpoints están bajo la URL base https://api.fypay.me/api, sin prefijo adicional:
| Endpoint | Método | Descripción |
|---|---|---|
/api/cob/:txid | PUT | Crear un cobro inmediato (PIX QR Code) |
/api/pix/:e2eid/devolucao/:id | PUT | Solicitar una devolución de un PIX recibido |
/api/dict/pix | POST | Iniciar una transferencia PIX (Cash-Out) |
/api/accounts/balances | GET | Consultar saldo de la cuenta |
Comparacion con la API estandar
| Operación | API Estandar | 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 |
| Devolución | POST /api/pix/refund-in/:id | PUT /api/pix/:e2eid/devolucao/:id |
| Saldo | GET /api/balance | GET /api/accounts/balances |
Flujo de integración
sequenceDiagram
participant Client
participant FyPay
participant BACEN
Note over Client,BACEN: 1. Autenticación
Client->>FyPay: POST /api/auth/token
FyPay-->>Client: access_token
Note over Client,BACEN: 2. Crear Cobro
Client->>FyPay: PUT /api/cob/\{txid\}
FyPay->>BACEN: Registrar cobro
FyPay-->>Client: QR Code + datos
Note over Client,BACEN: 3. Pago (via app bancaria)
BACEN->>FyPay: Webhook de pago
FyPay->>Client: Webhook V2 (type: RECEIVE)