Trabajo de verificación de transacciones
Cada transacción Pix comienza como pendiente. En la mayoría de los casos, es rápidamente confirmada o rechazada por el PSTI, pero a veces esa confirmación se retrasa o se pierde. El trabajo de verificación de transacciones escanea periódicamente las transacciones atascadas en pendiente y solicita una actualización al PSTI.
Flujo de trabajo: Verificación de estado
Cómo funciona:- Después de un breve retraso (30 segundos), el trabajo verifica cualquier transacción aún marcada como pendiente.
- Si la transacción está confirmada, se marca como confirmada.
- Si falla, el sistema revierte el débito y actualiza el estado a fallido.
- Si aún está pendiente, el trabajo programa otra verificación.
Cola de reintentos de webhooks
Si tu sistema no logra procesar un webhook, por ejemplo, debido a un tiempo de espera agotado o un error del servidor, el plugin de Pix no se rinde. Las entregas de webhooks fallidas se añaden a una cola de reintentos con retroceso exponencial:
| Intento | Retraso antes del reintento |
|---|---|
| 1º | Inmediato |
| 2º | 10 segundos |
| 3º | 1 minuto |
| 4º | 5 minutos |
| … | Hasta 24 horas |
Recuperación de reversiones
En casos extremos raros, los intentos de reversión pueden tener éxito parcial, por ejemplo:
- El valor se acredita de vuelta al remitente.
- Pero el paso de confirmación se pierde
- O falla la entrega de un webhook
¿Qué hace esto confiable?
- Diseño con estado: Cada transacción Pix incluye un registro de auditoría completo y estado del ciclo de vida.
- Lógica de compensación integrada: Si algo falla, el sistema sabe cómo completarlo o deshacerlo de forma segura.
- Respeta la idempotencia: Los reintentos y trabajos repetidos no producirán resultados duplicados.
Parámetros configurables
Puedes ajustar el comportamiento de los trabajos usando las siguientes variables de entorno:
| Variable | Descripción | Predeterminado |
|---|---|---|
PENDING_JOB_INTERVAL | Con qué frecuencia verificar transacciones pendientes | 30 segundos |
MAX_TRANSACTION_RETRIES | Intentos máximos antes de marcar como fallido | 5 |
RETRY_BACKOFF_BASE | Retraso base para reintentos de webhook | 10 segundos |
MAX_RETRY_TTL | Duración máxima para reintentos de webhook | 24 horas |
Lo que necesitas hacer
No necesitas configurar nada; los trabajos son completamente gestionados por el plugin de Pix. Para asegurar que todo funcione sin problemas:
- Usa IDs únicos y rastreables para tus transacciones y cuentas.
- Monitorea la entrega de webhooks y los estados de las transacciones.
- Avísanos si necesitas soporte para reproducción de webhooks o visibilidad en la ejecución de trabajos.