INSTRUCTIVO

INSTRUCTIVO PARA LA COPIA NO CONTROLADA

Código: Versión:
IMPLEMENTACIÓN DE I-IDI-008 1.4
RECAUDO POR CAJA Fecha:
17/07/2019
Página 1 de 6

1. OBJETIVO
Orientar al personal técnico y desarrolladores externos en la correcta implementación del medio de pago por caja que
ofrece ZonaPAGOS
2. ALCANCE
Aplica para todos los comercios que deseen desarrollar el método de pago por caja
3. RESPONSABLES
Es responsabilidad del Gerente de I+D+I la aprobación de lo consignado en este documento, al igual que sus posibles
actualizaciones.
4. DEFINICIONES

5. CONDICIONES GENERALES
Para poder realizar la conexión entre ambos sistemas se debe construir una API Rest que permita la validación de
factura o facturas que se pagaran por caja en el banco y también el registro de los pagos exitosos que se hagan en
las cajas del banco relacionados a cada factura. Es importante saber que el API desarrollada por el comercio deber
ser expuesta a internet para su consumo vía HTTPS, es decir publicado en un sitio que este cifrado con certificado
digital.
6. PROCESO Y/O FLUJOGRAMA
A continuación, se expresan los requisitos para que cualquier comercio o empresa como cliente de Zona Virtual y en
uso del servicio de ZonaPAGOS, pueda implementar de forma correcta el Medio de pago por caja que ofrece
ZonaPAGOS con los bancos colombianos que tenga convenio, con conexión directa a su sistema de cartera o donde
se almacene la información de facturas y pagos de sus clientes.

El comercio debe desarrollar un API REST, que será consumida por ZonaPAGOS, en todos sus métodos a través de
POST, usando JSON, la cual debe cumplir específicamente con la estructura detallada a continuación:

6.1. CONSULTA DE FACTURAS

Se debe crear un método llamado consulta de facturas (post), el cual va a permitirle a ZonaPAGOS conocer,
si las facturas que está consultando el banco para el pago en caja, están correctas y disponibles para que el
usuario realice el pago.

6.1.1. Parámetros de entrada:

PARÁMETRO TIPO Y TAMAÑO DESCRIPCIÓN

Int
Campo identificación del comercio, en
Tamaño máximo: Diez
Id_Comercio ZonaPAGOS, este valor es una constante y llega
(10) caracteres
como parámetro de consulta en el método.
*Obligatorio*
String Password de identificación entre ZonaPAGOS y el
Tamaño máximo: Quince (15) API REST del comercio, para brindar una llave de
Password
caracteres. comunicación entre ambos servicios y evitar de
*Obligatorio* alguna forma la suplantación.
Int
Tamaño máximo: Ocho (8) Código que identifica el banco que está realizando
Id_Banco
caracteres la consulta.
*Obligatorio*
Corresponde al id del pago referenciado que se
String
generó en la factura PDF (Código de barras) y que
Tamaño máximo: Sesenta (60)
Referencia_pago agrupa las facturas que el usuario desea pagar en la
caracteres.
caja del banco. Con este parámetro es que se
*Obligatorio*
buscan las facturas en la base de datos para saber
 INSTRUCTIVO
INSTRUCTIVO PARA LA COPIA NO CONTROLADA
Código: Versión:
IMPLEMENTACIÓN DE I-IDI-008 1.4
RECAUDO POR CAJA Fecha:
17/07/2019
Página 2 de 6

si existen y se encuentran en estado pendiente de

pago. De tal forma que estén habilitadas para que el
usuario realice el pago por la caja del banco.
Contiene la lista de toda información adicional que
se quiera guardar a modo de log de la transacción
de consulta realizada por el banco, la cual va
String separada por Pipeline dentro de este parámetro.
Tamaño máximo: Doscientos 200
Info_Adicional
caracteres. La lista de campos se maneja en una cadena
*Opcional* separada por el carácter | (pipeline) ejemplo:
Codigo Convenio|Nit Banco|Fecha hora transacción

No se envía pipeline | al final

6.1.2. Parámetros de respuesta

PARÁMETRO TIPO Y TAMAÑO DESCRIPCIÓN

String
Tamaño máximo: Diez (10) En este campo se retorna la fecha en formato
Fecha_limite_pago
caracteres DD/MM/AAAA.
*Obligatorio*
Float En este campo se retorna el valor de la factura
Tamaño máximo: Doce (12) usando el punto (.), como separador decimal, con
Valor_factura
caracteres un máximo de 2 decimales para indicar los
*Obligatorio* centavos.
En este campo se retorna:
0, si la referencia de pago consultada, corresponde
Int a facturas válidas para el pago.
Tamaño máximo: Cuatro (4) 1, si la referencia de pago consultada no
Codigo_Estado
caracteres. corresponde o no tiene facturas asociadas para que
*Obligatorio* se realice el pago por caja.
2, si ocurrió un error técnico o inesperado en la
consulta de las facturas.
En este campo se retorna el texto correspondiente a
String cada código de estado, así:
Tamaño máximo: Sesenta 0: “Exitoso”.
Descripción_estado
(60) caracteres. 1: “Factura no disponible para pago / Cliente no
*Obligatorio* Existe”
2: “Ocurrió un error inesperado en la operación”
Contiene la lista de toda información adicional que
se requiere para dar una mejor identificación a la
consulta de la factura por parte del tercero que la
solicita, como por ejemplo GANA y otros conectados
String
de arquitectura similar.
Tamaño máximo: Doscientos
Info_Adicional
(200) caracteres.
La lista de campos se maneja en una cadena
*Opcional*
separada por el carácter | (pipeline) ejemplo:
XXX|YYY|ZZZZ

No se envía pipeline | al final

 INSTRUCTIVO
INSTRUCTIVO PARA LA COPIA NO CONTROLADA
Código: Versión:
IMPLEMENTACIÓN DE I-IDI-008 1.4
RECAUDO POR CAJA Fecha:
17/07/2019
Página 3 de 6

Para la consulta de GANA se deben retornar los

valores de la siguiente forma:

Id Cliente|Id Pago|Nombre|Apellido

6.2. REGISTRAR PAGOS

Se debe crear un método llamado registrar pagos (post), el cual le va a permitir a ZonaPAGOS registrar en el
sistema del comercio, los pagos registrados por la caja del banco y que son informados en línea.

6.2.1. Parámetros de entrada:

PARÁMETRO TIPO Y TAMAÑO DESCRIPCIÓN

Int
Campo identificación del comercio, en ZonaPAGOS,
Tamaño máximo: Diez (10)
Id_Comercio este valor es una constante y llega como parámetro
caracteres
de consulta en el método
*Obligatorio*
String Password de identificación entre ZonaPAGOS y el
Tamaño máximo: Quince (15) API REST del comercio, para brindar una llave de
Password
caracteres. comunicación entre ambos servicios y evitar de
*Obligatorio* alguna forma la suplantación.
Int
Tamaño máximo: Ocho (8) Código que identifica el banco que está realizando la
Id_Banco
caracteres transacción.
*Obligatorio*
Corresponde al id del pago referenciado que se
generó en la factura PDF (Código de barras) y que
String
agrupa las facturas que el usuario desea pagar en la
Tamaño máximo: Sesenta (60)
Referencia_pago caja del banco. Con este parámetro es que se
caracteres.
buscan las facturas en la base de datos para saber
*Obligatorio*
a cuantas facturas corresponde el pago realizado
por el usuario en la caja del banco.
String
Tamaño máximo: Treinta (30) Fecha en formato DD/MM/AAAA, en la cual el banco
Fecha_pago
caracteres. informa que se realizó el pago.
*Obligatorio*
float
Tamaño máximo: Doce (12)
Valor_pagado Valor pagado en la caja del banco.
caracteres.
*Obligatorio*
String
Tamaño máximo: Cuarenta (40) Código único que identifica la aprobación de la
Id_transacción
caracteres. transacción en el banco.
*Obligatorio*
String Contiene la lista de toda información adicional que
Tamaño máximo: Doscientos se quiera guardar a modo de log de la transacción
Info_adicional
(200) caracteres. de pago realizada por el banco, la cual viene
*Opcional* separada por Pipeline dentro de este parámetro.
 INSTRUCTIVO
INSTRUCTIVO PARA LA COPIA NO CONTROLADA
Código: Versión:
IMPLEMENTACIÓN DE I-IDI-008 1.4
RECAUDO POR CAJA Fecha:
17/07/2019
Página 4 de 6

La lista de campos se maneja en una cadena

separada por el carácter | (pipeline).
No se envía pipeline | al final

6.2.2. Parámetros de Respuesta.

PARÁMETRO TIPO Y TAMAÑO DESCRIPCIÓN

Código de error de la ejecución general de la
transacción:
Int 0: Exitoso, si se hizo la actualización del estado de
Tamaño máximo: Cinco (5) todas las facturas correctamente.
Codigo_estado
caracteres. 1: Fallido, si no se pudo realizar la actualización del
*Obligatorio* estado de una o más facturas de la transacción. 2, si
ocurrió un error técnico o inesperado en el proceso
de registro del pago de las facturas.
Severidad del Mensaje
String
I: Informativo
Severidad Tamaño máximo: Un (1) carácter
W: Warning
*Obligatorio*
E: Error
Mensaje descriptivo del error, teniendo en cuenta la
String
severidad:
Tamaño máximo: Sesenta (60)
Descripcion 0: Se realizó exitosamente la actualización del pago.
caracteres.
1: No se pudo realizar la actualización del pago.
*Obligatorio*
2: “Ocurrió un error inesperado en la operación”

6.3. REVERSAR PAGOS

Se debe crear un método llamado reversar pagos (post), el cual le va a permitir a ZonaPAGOS registrar en el
sistema del comercio, los pagos que sean reversados desde el sistema del banco.

6.3.1. Parámetros de entrada.

PARÁMETRO TIPO Y TAMAÑO DESCRIPCIÓN

Int
Campo identificación del comercio, en ZonaPAGOS,
Tamaño máximo: Diez (10)
Id_Comercio este valor es una constante y llega como parámetro
caracteres
de consulta en el método
*Obligatorio*
String Password de identificación entre ZonaPAGOS y el
Tamaño máximo: Quince (15) API REST del comercio, para brindar una llave de
Password
caracteres. comunicación entre ambos servicios y evitar de
*Obligatorio* alguna forma la suplantación.
Int
Tamaño máximo: Ocho (8) Código que identifica el banco que está realizando la
Id_Banco
caracteres transacción.
*Obligatorio*
String Corresponde al id del pago referenciado que se
Referencia_pago Tamaño máximo: Sesenta (60) generó en la factura PDF (Código de barras) y que
caracteres. agrupa las facturas sobre las cuales el banco está
 INSTRUCTIVO
INSTRUCTIVO PARA LA COPIA NO CONTROLADA
Código: Versión:
IMPLEMENTACIÓN DE I-IDI-008 1.4
RECAUDO POR CAJA Fecha:
17/07/2019
Página 5 de 6

*Obligatorio* reportando el reverso del pago. Con este parámetro

es que se buscan las facturas en la base de datos
para saber a cuantas facturas corresponde el pago
realizado por el usuario en la caja del banco, para
realizar el proceso de reverso.
String
Tamaño máximo: Treinta (30) Fecha en formato DD/MM/AAAA, en la cual el banco
Fecha_reverso
caracteres. informa que se realizó el reverso del pago.
*Obligatorio*
Float
Tamaño máximo: Doce (12) Valor del pago correspondiente que se desea
Valor_pagado
caracteres. reversar.
*Obligatorio*
String Código único que identifica la aprobación de la
Id_transacción Tamaño máximo: Cuarenta (40) transacción en el banco. Este es mismo que envió el
caracteres banco al momento de que se realizó el pago de la
*Obligatorio* obligación en la caja del banco.
Contiene la lista de toda información adicional que
se quiera guardar a modo de log de la transacción
de pago realizada por el banco, la cual viene
String
separada por Pipeline dentro de este parámetro.
Tamaño máximo: Doscientos
Info_adicional
(200) caracteres.
La lista de campos se maneja en una cadena
*Opcional*
separada por el carácter | (pipeline)

No se envía pipeline | al final

6.3.2. Parámetros de Respuesta.

PARÁMETRO TIPO Y TAMAÑO DESCRIPCIÓN

Código de error de la ejecución general de la
transacción:
Int 0: Exitoso, si se hizo el reverso del pago de forma
Tamaño máximo: Cinco (5) correcta.
Codigo_estado
caracteres. 1: Fallido, si no se pudo realizar el reverso de la
*Obligatorio* transacción.
2, si ocurrió un error técnico o inesperado en el
proceso de reverso de la transacción.
Severidad del Mensaje
String
I: Informativo
Severidad Tamaño máximo: Un (1) caracter
W: Warning
*Obligatorio*
E: Error
Mensaje descriptivo del error, teniendo en cuenta la
String
severidad:
Tamaño máximo: Sesenta (60)
Descripcion 0: Se realizó exitosamente el reverso del pago
caracteres.
1: No se pudo realizar el reverso del pago.
*Obligatorio*
2: “Ocurrió un error inesperado en la operación”
 INSTRUCTIVO
INSTRUCTIVO PARA LA COPIA NO CONTROLADA
Código: Versión:
IMPLEMENTACIÓN DE I-IDI-008 1.4
RECAUDO POR CAJA Fecha:
17/07/2019
Página 6 de 6

7. CONTROL DE CAMBIO

VERSIÓN FECHA DESCRIPCIÓN DEL CAMBIO

1.0 01/12/2014 Versión Inicial.
1.1 11/02/2015 Se adiciona al documento la descripción técnica del método de reverso de pagos.
Se adiciona el parámetro info_adcional en el response de la consulta para recibir pagos
1.2 11/02/2016
que son necesarios con la conexión con GANA y otros terceros de arquitectura similar.
Se cambia el nombre de la variable “Total_pagado” en los métodos de “registrar pago” y
1.3 14/04/2016
“reversar pagos” por “Valor_pagado”
1.4