1. Usa una clave de pago idempotente
En un flujo de pago de Pix Lerian, el header
X-Idempotency es tu clave de idempotencia. Envía un valor nuevo para cada solicitud y reutilízalo solo para reintentar esa solicitud. El endToEndId de BACEN no es la clave de reintento.
Trata el valor de X-Idempotency como tu clave de idempotencia:
- Si reintentas una solicitud después de un timeout, reutiliza el mismo valor de
X-Idempotency. - Si el primer intento tuvo éxito, Pix Lerian reproduce su respuesta durante una hora.
- Si el primer intento falló con un
5xx, o si la hora ya pasó, lee el estado de la operación antes de reintentar. - Dentro de esa hora, si reutilizas el valor con una solicitud diferente, Pix Lerian la rechaza.
- Asientos duplicados en el ledger
- Débitos dobles
- Correcciones operativas manuales
- Inconsistencias de conciliación
endToEndId. Los caracteres 2 a 9, después de la E inicial, deben contener tu ISPB. En un pago por clave o por QR Code, envíalo al iniciar la transferencia u omítelo, y Pix Lerian genera uno. La iniciación devuelve el valor, y el procesamiento lo reutiliza. No envíes X-End-To-End-Id al procesar un pago por clave o por QR Code: Pix Lerian lo rechaza. En un pago manual, envía el valor en X-End-To-End-Id al procesar la transferencia.
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.
Confirma el estado final por webhook o por Get Transfer:
- 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, pero 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