1. Usa IDs de transacción idempotentes
Siempre envía un
transactionId único e inmutable creado por tu sistema.
Trátalo como tu clave de idempotencia:
- Si reintentas una solicitud debido a timeout, reutiliza el mismo ID.
- Si el primer intento tuvo éxito, el Plugin Pix devolverá el mismo resultado.
- Si el primer intento falló antes del procesamiento, el reintento creará la transacción exactamente una vez.
- Registros duplicados en el libro mayor
- Débitos dobles
- Correcciones operacionales manuales
- Inconsistencias de conciliación
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 Plugin Pix
- 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