1. Usa una clave de pago idempotente
En el flujo de pago Pix, el
endToEndId de BACEN es tu clave de idempotencia. Es un identificador único e inmutable de 32 caracteres que tú entregas o que genera Pix Lerian. Solo puedes reintentar de forma segura cuando el valor es tuyo.
Trata el endToEndId como tu clave de idempotencia:
- Si reintentas una solicitud después de un timeout, reutiliza el mismo
endToEndId. - Si el primer intento ya creó el pago, Pix Lerian reproduce el existente.
- Si el primer intento falló antes del procesamiento, el reintento crea el pago exactamente una vez.
- Asientos duplicados en el ledger
- Débitos dobles
- Correcciones operativas manuales
- Inconsistencias de conciliación
endToEndId para un reintento.
Para el comportamiento de idempotencia en el nivel de header de cada producto Lerian, consulta Reintentos e idempotencia.
2. Confía en los webhooks para el estado final de la transacción
Un
200 OK de la API no garantiza que el Pix se completó.
Solo significa que la solicitud entró en el flujo de orquestación.
El estado autoritativo es el del webhook:
- Muestra el estado final al usuario solo después de la confirmación por webhook
- Persiste el estado del webhook en tu sistema
- Gestiona tanto las notificaciones de éxito como las de fallo
3. Valida la autenticidad del webhook
Cada webhook incluye una firma HMAC (por ejemplo,
X-Signature).
Mejores prácticas:
- Guarda el secreto en una bóveda
- Recalcula el HMAC usando el cuerpo crudo de la solicitud
- Compara con el header
- Rechaza y registra las discrepancias
- Callbacks falsos
- Payloads manipulados
- Solicitudes no autorizadas que llegan a tu endpoint
4. Diseña para fallos y reintentos
Pix es instantáneo. La red a su alrededor no lo es. Espera fallos en:
- Conectividad del PSTI / proveedor directo
- Entrega de telecomunicaciones / SMS (para la confirmación de claves)
- Timeouts de red
- Validaciones internas del ledger
- Comprobaciones de límites y antifraude (reguladas)
- Implementa políticas de reintento claras (backoff exponencial, bucles controlados)
- Nunca reintentes a ciegas
- Muestra al usuario mensajes accionables
- Registra todos los fallos con IDs de correlación
- Trata “pending” como un estado intermedio normal
5. Monitorea las transacciones pendientes y los jobs en segundo plano
Un Pix puede entrar en PENDING mientras espera:
- El procesamiento del proveedor
- El acuse de recibo del SPI
- La entrega del webhook
- Ciclos de reintento
- Reintentar callbacks
- Conciliar estados intermedios
- Detectar operaciones atascadas
- Monitorear las transacciones pendientes con regularidad
- Configurar alertas para intentos de reintento excesivos
- Integrar logs, métricas y trazas para la observabilidad
6. Mantén las claves Pix y los datos de clientes sincronizados
Como las claves están ligadas a la identidad:
- Si un usuario cambia de teléfono/correo → actualiza o elimina las claves Pix asociadas
- Mantén los registros del CRM alineados con los datos del DICT
- Elimina las claves desactualizadas para evitar enrutamientos erróneos
- Para las instituciones que usan DICT: Confirma que las reclamaciones de portabilidad y titularidad siguen las reglas de BACEN
- Pagos a receptores equivocados
- Casos de MED por claves incorrectas
- Fricción en soporte
7. Respeta las expectativas de SLA y las ventanas de tiempo
La liquidación de Pix ocurre en hasta 10 segundos, pero los SLA legales también cuentan. Diseña tu UX para respetar:
- Las tolerancias máximas del SPI
- Los ajustes de límite nocturno (20:00–06:00)
- Los plazos de reducción de límite pedida por el cliente (inmediata)
- Los aumentos de límite pedidos por el cliente (pueden requerir autenticación o un período de espera)
- “Procesando…” mientras esperas la confirmación
- Orientación de “Intentar de nuevo” para límites superados
8. Implementa conciliación y validación contable
La conciliación cierra el ciclo entre:
- Tu sistema
- Pix Lerian
- La liquidación en el SPI
- Los asientos del ledger (Midaz)
- Confirma cada Pix liquidado con tu log de webhooks
- Haz coincidir cada ID de Pix con un asiento del ledger
- Compara los resúmenes diarios con las salidas del proveedor/SPB
- Marca cualquier discrepancia para revisión manual
9. Prueba de extremo a extremo con flujos realistas
Antes de entrar en producción, simula:
- Cash-in y cash-out
- Límites de alto valor
- Claves inválidas
- QR Codes expirados
- Devoluciones (entrantes + salientes)
- Disparadores de devolución relacionados con MED
- Caídas de webhooks
- Patrones de timeout y reintento de la API
- Asientos del ledger correctos
- Transiciones de estado de Pix correctas
- Manejo adecuado de webhooks
- Aplicación adecuada de límites
- Comportamiento contable adecuado
10. Prepara tus equipos de soporte y operaciones
Se recomienda que los equipos de soporte entiendan:
- Los plazos de Pix (incluidas las reglas de límite nocturno)
- La diferencia entre “initiated”, “pending”, “completed”, “refunded”, “failed”
- Cómo leer los IDs E2E
- Cómo dar seguimiento a los problemas del DICT
- Cuándo aplica MED frente a las devoluciones normales