👥 API REST Zonapagos
⚙️ Especificación de Parámetros
🔍Verificación del Estado del Pago
Esta guía describe la integración técnica de la Pasarela de Pagos Zonapagos mediante API REST, utilizando un flujo de redirección. Está dirigida a desarrolladores backend responsables de integraciones seguras entre el comercio y Zonapagos.
Zonapagos provee las credenciales necesarias para la integración:
Existen credenciales independientes para ambientes de pruebas y producción. Las credenciales deben almacenarse de forma segura y nunca exponerse en repositorios públicos.
Cada transacción debe contar con una referencia única (str_id_pago).
Los parámetros se agrupan en:
Todos los campos obligatorios deben enviarse para evitar errores de validación.
URL: https://www.Zonapagos.com/Apis_CicloPago/api/InicioPago
Método: POST
Content-Type: application/json
El servicio retorna una URL (str_url) a la cual debe redireccionarse el usuario.
El servicio responde indicando si la ejecución fue correcta.
Nota: Una ejecución correcta NO implica que el pago esté aprobado.
El comercio debe redireccionar al usuario usando la URL retornada (str_url).
Una vez el comercio obtiene una respuesta exitosa del servicio InicioPago, el campo str_url contendrá la URL del ciclo de pago.
El comercio debe redireccionar al usuario pagador a esta URL para que continúe el proceso de pago directamente en la pasarela de Zonapagos.
La redirección no garantiza que el pago haya sido aprobado.
El usuario puede abandonar el proceso o la entidad financiera puede tardar en confirmar la transacción.
Zonapagos realiza una notificación vía GET a una URL del comercio.
La notificación no confirma el pago.
Siempre debe validarse el estado final usando el servicio VerificacionPago.
Al finalizar o avanzar el proceso de pago, Zonapagos realizará una llamada HTTP GET a la URL de notificación configurada por el comercio.
Esta llamada incluirá los siguientes parámetros:
Ejemplo:
Url definida por el comercio:
https://micomercio.com.co/pagos/notificacion
Url final con parámetros:
https://micomercio.com.co/pagos/notificacion?id_comercio=17485&id_pago=4651abc
La notificación no confirma el estado final del pago.
Su función es informar al comercio que debe consultar el estado de la transacción.
Durante el ciclo de una transacción, el usuario pagador puede ser redirigido a una URL del comercio.
Esta URL pertenece al sitio web del comercio y se utiliza únicamente para redirigir al usuario una vez finalizado o interrumpido el flujo visual del pago.
La URL de retorno puede definirse de dos formas:
Si no se envía una URL dinámica, se utilizará la URL configurada por defecto para el comercio.
Para determinar el estado real de una transacción, el comercio debe consumir el servicio VerificacionPago.
Este servicio es la única fuente confiable para determinar si un pago fue:
Nota importante:
En ninguna circunstancia se debe actualizar el estado del pago únicamente con la notificación o la redirección del usuario.