Requisitos técnicos
Sonda implementada correctamente. Consulta pagos pendientes cada 10-15 minutos (cada 1 hora para pagos presenciales), con lock para evitar concurrencia. Ver Implementar la sonda.
Manejo de todos los estados de
int_estado_pago: 1, 888, 999, 1000, 1001, 4000, 4001, 4003. Ver Estados de pago.No duplicar pagos. Cada pedido usa un
str_id_pago único. Callback idempotente. Ver Idempotencia.Persistencia del CUS (
str_codigo_transaccion). Necesario para reclamos ante el banco.Datos obligatorios del pagador:
str_id_cliente, str_tipo_id, flt_valor_iva deben enviarse en todo InicioPago PSE.Mensajes obligatorios al usuario para estados
999 y 4001 (ver abajo).Requisitos de experiencia y legales
Mostrar al usuario el resultado de cada pago (no dejarlo en limbo).
Permitir consultar el estado de un pago desde tu sitio.
No mostrar errores técnicos crudos al usuario final.
Términos y condiciones publicados y aceptados antes del pago.
Política de privacidad que contemple el flujo de datos.
Información visible del comercio: razón social, NIT, dirección.
Contactos de soporte visibles en el sitio.
Procedimiento de reembolso documentado.
Mensajes obligatorios al usuario
Cuando consultasVerificacionPago y recibes un estado pendiente, debes mostrar al usuario los siguientes textos. La redacción fue validada por ACH Colombia y PSE exige que se use de forma literal para certificar.
Estado 999 — Pendiente por finalizar (PSE)
Cuando int_estado_pago: 999 con int_id_forma_pago: 29:
En este momento su Número de Referencia o Factura (id_Pago) presenta un proceso de pago cuya transacción se encuentra PENDIENTE de recibir confirmación por parte de su entidad financiera, por favor espere unos minutos y vuelva a consultar más tarde para verificar si su pago fue confirmado de forma exitosa. Si desea mayor información sobre el estado actual de su operación puede comunicarse a nuestras líneas de atención al cliente 57-1-9999999 o enviar un correo electrónico a email@email.com.co y preguntar por el estado de la transacción: <#CUS>
| Variable | Fuente |
|---|---|
(id_Pago) | El str_id_pago del pedido. |
57-1-9999999 | Tu número de atención al cliente. |
email@email.com.co | Tu email de soporte. |
<#CUS> | El valor del campo str_codigo_transaccion de str_res_pago. |
Estado 4001 — Pendiente CR (Tarjeta de Crédito)
Cuando int_estado_pago: 4001 con int_id_forma_pago: 32:
En este momento su Número de Referencia o Factura (id_Pago) presenta un proceso de pago cuya transacción se encuentra PENDIENTE de recibir confirmación por parte de su entidad financiera, por favor espere unos minutos y vuelva a consultar más tarde para verificar si su pago fue confirmado de forma exitosa. Si desea mayor información sobre el estado actual de su operación puede comunicarse a nuestras líneas de atención al cliente 57-1-9999999 o enviar un correo electrónico a email@email.com.co.
Implementación sugerida
Dónde mostrarlo
- En la página que ve el usuario tras el callback cuando el estado es pendiente.
- En consultas posteriores desde “Mis pedidos” si el pago sigue pendiente.
- En el email de notificación al usuario, si lo envías.
Proceso de certificación
Auto-evaluación
Revisa esta página y el checklist de producción. Marca cada ítem.
Solicitud formal
Escribe a soporte@zonavirtual.com.co con asunto
[CERTIFICACIÓN PSE] indicando tu int_id_comercio.Sesión de pruebas
Se agenda una sesión (1-2 horas). Comparte pantalla y demuestras el flujo completo.
Validación de escenarios
Se verifican los casos: aprobado, rechazado, pendiente (999), CR (4001), abandonado.
Escenarios que te pedirán demostrar
| Escenario | Qué se valida |
|---|---|
Pago aprobado (1) | Callback, VerificacionPago, marca en BD, email, persistencia del CUS. |
Pago rechazado (1000/1001) | Marca en BD, mensaje amigable, permitir reintento con nuevo str_id_pago. |
Pago pendiente (999) | Mensaje obligatorio con CUS, sonda consultando, actualización al resolverse. |
Pago abandonado (888 sostenido) | Marca como abandonado tras 30 min sin evolución. |
| Reintento | Usuario puede pagar de nuevo con nuevo str_id_pago. |
| Idempotencia del callback | Recargar la página de retorno no procesa el pago dos veces. |
| Credenciales inválidas | Tu sistema maneja int_codigo: 2 sin crashear. |
Consecuencias de no certificar correctamente
Operar PSE sin cumplir estos requisitos puede llevar a suspensión por ACH Colombia, auditoría retrospectiva, sanciones económicas y pérdida de confianza de usuarios finales. Zonapagos tiene responsabilidad solidaria ante ACH, por lo que un incumplimiento de tu parte también nos afecta a nosotros.Ver también
Checklist producción
Lista completa antes de salir a producción.
Implementar sonda
Componente clave para la certificación.