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ú envías, o que Pix Switch genera. Solo puedes reintentar de forma segura cuando controlas el valor.
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 Switch hace replay del existente.
- Si el primer intento falló antes del procesamiento, el reintento crea el pago exactamente una vez.
- Registros duplicados en el libro mayor
- Débitos dobles
- Correcciones operacionales manuales
- Inconsistencias de conciliación
endToEndId para un reintento.
Para el comportamiento de idempotencia a 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 webhook:
- Muestra el estado final al usuario solo después de la confirmación del webhook
- Persiste el estado del webhook en tu sistema
- Maneja tanto notificaciones de éxito como de falla
3. Valida la autenticidad del webhook
Cada webhook incluye una firma HMAC (ej.,
X-Signature).
Mejores prácticas:
- Almacena el secreto en una bóveda
- Recalcula el HMAC usando el cuerpo de la solicitud sin procesar
- Compara con el header
- Rechaza y registra las discrepancias
- Callbacks falsos
- Payloads manipulados
- Solicitudes no autorizadas llegando a tu endpoint
4. Diseña para fallas y reintentos
Pix es instantáneo. La red a su alrededor no lo es. Espera fallas en:
- Conectividad PSTI / proveedor directo
- Entrega de Telecom / SMS (para confirmación de claves)
- Timeouts de red
- Validaciones internas del libro mayor
- Verificaciones de límites y antifraude (reguladas)
- Implementa políticas de reintento claras (backoff exponencial, loops controlados)
- Nunca reintentas ciegamente
- Muestra mensajes accionables al usuario
- Registra todas las fallas con IDs de correlación
- Trata “pendiente” como un estado intermediario normal
5. Monitorea transacciones pendientes y trabajos en segundo plano
Un Pix puede entrar en PENDING mientras espera:
- Procesamiento del proveedor
- Reconocimiento de SPI
- Entrega de webhook
- Ciclos de reintento
- Reintentar callbacks
- Conciliar estados intermedios
- Detectar operaciones atascadas
- Monitorea transacciones pendientes regularmente
- Configura alertas para intentos de reintento excesivos
- Integra logs, métricas y trazas para observabilidad
6. Mantén las claves Pix y datos de clientes sincronizados
Porque las claves están vinculadas a la identidad:
- Si un usuario cambia teléfono/correo electrónico → actualiza o elimina las claves Pix asociadas
- Mantén los registros de CRM alineados con los datos de DICT
- Elimina claves desactualizadas para evitar enrutamiento incorrecto
- Para instituciones que usan DICT: Asegura que los reclamos de portabilidad y propiedad sigan las reglas de BACEN
- Pagos a destinatarios incorrectos
- Casos MED debido a claves incorrectas
- Fricción de soporte
7. Respeta las expectativas de SLA y ventanas de tiempo
La liquidación de Pix ocurre en hasta 10 segundos, pero los SLAs legales también importan. Diseña tu UX para respetar:
- Tolerancias máximas de SPI
- Ajustes de límites nocturnos (20:00–06:00)
- Retrasos en reducción de límites controlados por el cliente (inmediatos)
- Aumentos de límites controlados por el cliente (pueden requerir autenticación o período de espera)
- “Procesando…” mientras esperas confirmación
- Guía de “Intentar de nuevo” para violaciones de límites
8. Implementa conciliación y validación contable
La conciliación cierra el ciclo entre:
- Tu sistema
- El Pix Switch
- Liquidación de SPI
- Registros en el libro mayor (Midaz)
- Confirma cada Pix liquidado usando tu log de webhooks
- Empareja cada ID de Pix con un registro en el libro mayor
- Compara resúmenes diarios con salidas de 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
- Códigos QR expirados
- Reembolsos (entrantes + salientes)
- Disparadores de reembolso relacionados con MED
- Tiempo de inactividad del webhook
- Patrones de timeout y reintento de API
- Registros correctos en el libro mayor
- Transiciones de estado de Pix correctas
- Manejo apropiado de webhooks
- Aplicación apropiada de límites
- Comportamiento contable apropiado
10. Prepara a tus equipos de soporte y operaciones
Los equipos de soporte deben entender:
- Plazos de Pix (incluyendo reglas de límites nocturnos)
- Diferencia entre “iniciado”, “pendiente”, “completado”, “reembolsado”, “fallido”
- Cómo leer IDs E2E
- Cómo rastrear problemas de DICT
- Cuándo aplica MED vs reembolsos normales