Skip to main content

¿Qué es la sonda?

La sonda (SONDA, cron job, tarea programada) es un proceso en tu backend que cada 10-15 minutos consulta VerificacionPago para todos los pagos en estado pendiente, y actualiza su estado local cuando recibe respuesta definitiva.
La sonda es obligatoria para la certificación PSE. Sin ella, PSE no certifica tu comercio y no puedes operar PSE en producción.

¿Por qué es necesaria?

PSE y ciertos flujos de tarjeta de crédito no responden de forma síncrona. Un pago puede quedar en estado 999 (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

Mensajes obligatorios al usuario

Si un usuario consulta el estado de su pago y recibe 999 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.