Skip to main content
Al cierre de esta documentación no hay un endpoint REST sandbox público. El formulario ASPX dummie (dummie_ciclopago/FormulariosWeb/InicioPago_Dummie.aspx) sirve para probar el flujo visual, pero dummie_ciclopago/api/* retorna HTTP 404.Para probar el API REST, contacta a soporte@zonapagos.com para solicitar credenciales de preproducción.
El instructivo oficial v6.0 tiene una contradicción en este punto: el texto dice “siempre enviar -1”, pero el ejemplo JSON usa 1.Recomendación provisional: usar -1 siguiendo el texto normativo. [Pendiente de confirmación con TI.]
Ese es un mensaje de excepción .NET que el API devuelve cuando encuentra un problema de validación interno. Causas típicas:
  • Credenciales inválidas.
  • int_id_comercio inexistente.
  • Falta algún objeto top-level en el body (InformacionPago, InformacionSeguridad, AdicionalesPago, AdicionalesConfiguracion).
  • Estás usando credenciales del ambiente dummie contra el API REST de producción.
Revisa credenciales y estructura del JSON. Si persiste, contacta a soporte con el timestamp del intento.
Es así en el API. Contienen el mismo valor pero con nombres distintos:No es un typo, es la convención histórica del API.
Cuando int_estado_pago === 1 en la respuesta de /VerificacionPago. Este es el único estado que significa aprobado. Nunca asumas aprobación porque:
  • Recibiste el callback (puede ser falso).
  • int_codigo: 1 en InicioPago (solo significa que creaste la transacción).
  • El usuario dice “ya pagué”.
No. Cada pago debe tener un str_id_pago único. Si el usuario quiere reintentar, genera un nuevo ID (ej. ORDEN-001-R1, ORDEN-001-R2).Reutilizar IDs puede causar conflictos en el core transaccional y errores difíciles de depurar.
Es texto plano con separadores | (campos) y |;| (pagos). Tenemos parsers listos para copiar en:Ver también Parsear str_res_pago con el código detallado.
Sí, si aceptas PSE. Sin sonda, PSE / ACH Colombia no certifica tu comercio y no puedes operar PSE en producción.Para comercios que solo aceptan tarjeta de crédito (sin PSE), la sonda es altamente recomendada pero no exigida por certificación. Te recomendamos implementarla igual para manejar el estado 4001 (pendiente CR).
Significa que la franquicia retuvo la tarjeta para revisión antifraude. El pago puede resolverse en minutos o tardar hasta 1 día y fracción. Pasado ese tiempo, queda automáticamente rechazado.Tu acción:
  1. Mostrar el mensaje obligatorio al usuario.
  2. Configurar tu sonda para consultar cada 10-15 min.
  3. No permitir al usuario reintentar con el mismo str_id_pago mientras esté en CR.
No. El callback solo incluye id_comercio e id_pago sin firma HMAC ni token verificable.Mitigación obligatoria: siempre verifica el estado real llamando /VerificacionPago desde tu backend. Nunca entregues producto confiando solo en el callback.[Pendiente con TI: evaluar incorporación de firma al callback.]
No los uses. El documento oficial indica que no se deben usar ceros al inicio. Ejemplos:
  • ✅ "ORDEN-001", "180924", "FAC-2026"
  • ❌ "009", "0123", "00ORDEN"
Si tu sistema interno genera IDs con ceros, añade un prefijo: "P-009" en lugar de "009".
Depende del banco:
  • La mayoría: 30 segundos a 5 minutos.
  • Casos con red saturada: hasta 30 minutos en estado 999.
  • Casos excepcionales: hasta algunas horas.
Tu sonda debe manejar los tiempos variables. Si un pago lleva más de 24 horas en 999, algo raro está pasando — revisa manualmente o contacta soporte.
El campo acepta 4 dígitos donde los dos últimos son decimales:
Envía siempre como string con padding de ceros a la izquierda.
La documentación oficial también menciona una convención alternativa de 2 dígitos ("02" = 2%). Para evitar ambigüedades usa la de 4 dígitos.
Es diferente de int_estado_pago:
  • int_pago_terminado: 200 → pago iniciado (aún no ha pasado nada).
  • int_pago_terminado: 1 → pago cerrado (aprobado o rechazado).
  • int_pago_terminado: 2 → pago mixto incompleto (aún faltan sub-pagos por terminar).
Para saber si fue aprobado, mira int_estado_pago (debe ser 1).
Sí, si enviaste str_email en el InicioPago. Zonapagos le manda un comprobante del pago (estilo recibo con el CUS).Esto no reemplaza tu email de “gracias por tu compra” con el detalle del producto — eso lo debes enviar tú.
Los campos clave que debes persistir:
  • PSE: str_codigo_transaccion (CUS), int_codigo_banco, str_nombre_banco, dat_fecha.
  • TC: int_cod_aprobacion, str_franquicia, int_numero_tarjeta (últimos 4), dat_fecha.
  • Otros: str_ticketID, int_codigo_banco.
Estos datos te los entregan bancos y franquicias en los archivos de liquidación diaria.
El tiempo de procesamiento depende del medio de pago utilizado. Por ejemplo, para ACH el tiempo habitual oscila entre 5 y 15 minutos, aunque en casos particulares puede acercarse a los 30 minutos.
Como referencia, se recomienda configurar la ejecución de la sonda entre 5 y 7 minutos o entre 10 y 12 minutos. Sin embargo, cada comercio puede definir el intervalo que mejor se adapte a su operación, procurando evitar ciclos demasiado cortos que generen un consumo excesivo del servicio.
La ruta GET es un requisito obligatorio para las integraciones. No obstante, el comercio puede solicitar formalmente por correo electrónico la autorización para salir a producción utilizando únicamente la sonda de consulta.
En caso de aprobarse la solicitud, el comercio deberá informar a sus usuarios que, después de realizar un intento de pago, deben esperar un tiempo prudente antes de consultar el estado de la transacción o intentar un nuevo pago. Asimismo, el comercio será responsable de consultar el estado de cada transacción mediante la sonda, ya que no contará con notificaciones automáticas por parte de Zonapagos.
La solicitud debe enviarse formalmente por correo electrónico. Una vez recibida, será escalada para su evaluación y la respuesta de aprobación o rechazo se comunicará por el mismo medio.

​
¿No encuentras tu pregunta?

Errores comunes

Tabla de errores con diagnóstico.

Contactar soporte

Escríbenos con los detalles de tu caso.