¿Qué es la sonda?
La sonda (SONDA, cron job, tarea programada) es un proceso en tu backend que cada 10-15 minutos consultaVerificacionPago para todos los pagos en estado pendiente, y actualiza su estado local cuando recibe respuesta definitiva.
¿Por qué es necesaria?
PSE y ciertos flujos de tarjeta de crédito no responden de forma síncrona. Un pago puede quedar en estado999 (pendiente por finalizar) o 4001 (pendiente CR) por varios minutos o incluso horas. Si tu backend no tiene un proceso que consulte periódicamente, queda desincronizado con Zonapagos.
Casos típicos:
- Usuario autoriza débito PSE en el banco, pero el banco demora en confirmar ante ACH.
- Franquicia retiene TC por revisión antifraude (
4001). - Pago presencial (GANA, Efecty) — el usuario toma 1-2 días en ir al punto físico.
Reglas de negocio
1
Frecuencia estándar: cada 10-15 minutos
Para pagos en línea (PSE 29, TC 32, Bancolombia 48, Codensa 51).
2
Frecuencia reducida: cada 1 hora
Para pagos presenciales (
int_id_forma_pago = 41 PDF, 77 Mefía). Marca estos pagos en tu BD con un flag al detectar el medio.3
Solo consultar si han pasado >7 minutos de iniciado el pago
Antes de eso, PSE/franquicia aún está procesando. Consultar antes es desperdicio.
4
Estados definitivos → dejar de consultar
Si
int_estado_pago es 1, 1000, 1001, 4000, o 4003, ya no cambiará. Marca el pago como cerrado en tu BD.5
Tiempo máximo de reintentos: 1 día y fracción para CR
Pasado ese tiempo, las transacciones en
4001 quedan automáticamente rechazadas.Funcionamiento de la sonda

Implementación paso a paso
1. Schema de base de datos
Asegúrate de tener estos campos en tu tabla de pagos:2. Query de pagos a consultar
3. Código de la sonda (Node.js)
4. Cómo programarla
- cron (Linux)
- Kubernetes CronJob
- AWS EventBridge + Lambda
Mensajes obligatorios al usuario
Si un usuario consulta el estado de su pago y recibe999 o 4001, debes mostrar un mensaje específico (requerimiento PSE). Ver Mensajes de certificación.
Buenas prácticas
concurrencyPolicy: Forbid — evita que dos instancias de la sonda corran simultáneamente y causen race conditions.Timeout razonable en el request (15 segundos). Sin timeout, un VerificacionPago lento bloquea toda la sonda.
Paginación implícita — procesa máximo 100-200 pagos por iteración. Si tienes más pendientes, la siguiente iteración los recoge.
Logs estructurados — cada consulta con
str_id_pago, timestamp, resultado. Útil para auditoría PSE.Alerta si un pago lleva >24h pendiente — probablemente quedó huérfano. Revisa manualmente.
No elimines pagos pendientes automáticamente. Cerrarlos como “abandonado” es preferible a borrarlos.
Errores comunes
Ver también
Mensajes de certificación
Textos obligatorios para 999 y 4001.
Requisitos certificación PSE
Checklist completo.