Skip to main content
Si tu comercio va a procesar pagos por PSE, debe ser certificado ante ACH Colombia antes de operar en producción. Sin certificación, PSE no habilita tus transacciones, aunque el resto de la integración esté lista.

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 consultas VerificacionPago 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>
Variables a reemplazar:
VariableFuente
(id_Pago)El str_id_pago del pedido.
57-1-9999999Tu número de atención al cliente.
email@email.com.coTu 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.
Diferencia con PSE: en TC no hay CUS, por lo que se omite la referencia al código de transacción.

Implementación sugerida

function mensajePendiente(pago) {
  const telefono = process.env.SOPORTE_TELEFONO;
  const email = process.env.SOPORTE_EMAIL;

  const base = `En este momento su Número de Referencia o Factura (${pago.str_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 ${telefono} o enviar un correo electrónico a ${email}`;

  if (pago.int_id_forma_pago === 29 && pago.str_codigo_transaccion) {
    return `${base} y preguntar por el estado de la transacción: ${pago.str_codigo_transaccion}.`;
  }
  return `${base}.`;
}

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

1

Auto-evaluación

Revisa esta página y el checklist de producción. Marca cada ítem.
2

Solicitud formal

Escribe a soporte@zonavirtual.com.co con asunto [CERTIFICACIÓN PSE] indicando tu int_id_comercio.
3

Sesión de pruebas

Se agenda una sesión (1-2 horas). Comparte pantalla y demuestras el flujo completo.
4

Pruebas con montos bajos

Típicamente entre 1.000y1.000 y 5.000 COP por transacción.
5

Validación de escenarios

Se verifican los casos: aprobado, rechazado, pendiente (999), CR (4001), abandonado.
6

Validación de mensajes

Se verifica que los mensajes obligatorios aparezcan correctamente.
7

Certificación emitida

Tras aprobación, se notifica a ACH y se habilita PSE en producción.

Escenarios que te pedirán demostrar

EscenarioQué 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.
ReintentoUsuario puede pagar de nuevo con nuevo str_id_pago.
Idempotencia del callbackRecargar la página de retorno no procesa el pago dos veces.
Credenciales inválidasTu 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.