ZP-A-021 - INT

Pasarela de pagos versión REST

Versión 1.0

ZONA VIRTUAL S.A.

INSTRUCTIVO PARA REALIZACIÓN DE PASARELA DE

PAGOS VERSION REST– COMERCIOS.

ZP-A-021 – INT-
Pasarela de pagos
versión REST.
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

ZONA VIRTUAL S.A.

Pasarela de pagos versión REST

 Zona Virtual S.A.

www.zonavirtual.com
Teléfonos (+574)268 8437 • (+571)804 7959

i
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

Fecha ELABORÓ Descripción REVISÓ APROBÓ

Ing. Alexander Pasarela de pagos Ing. Juan Ing. Juan

29/05/2014
Blandón López versión REST Fernando Arango. Fernando Arango.

Se agregó el control
Ing. Alexander Ing. Juan Ing. Juan
13/10/2014 de transacciones
Blandón López Fernando Arango. Fernando Arango.
pendientes por CA

Se modificó la
Juan Camilo forma de interpretar Ing. Juan Ing. Juan
20/04/2016
Pérez Mejía los diferentes Fernando Arango. Fernando Arango.
estados de pago

Control de cambios.

ZP-A-021 - INT
Versión 2.0, 29 de Mayo de 2014

ADVERTENCIA SOBRE CONFIDENCIALIDAD.

La información contenida en este documento, incluyendo sus anexos, está dirigida exclusivamente a su destinatario
y contiene datos de carácter confidencial protegidos por la ley. Si usted no es el destinatario de este documento por
favor infórmenos y elimínelo a la mayor brevedad. soporte@zonavirtual.com

ii
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

Tabla de contenido
Fecha ii

ELABORÓ ii

Descripción ii

REVISÓ ii

APROBÓ ii

Control de cambios. ii

INICIO Y FINALIZACIÓN DE PAGOS. 1

1. Inicio de pago mediante consumo del

REST. 1

2. Recepción de parámetros de resultado del

pago por GET 7

VERIFICACIÓN O CONSULTA DEL ESTADO DE

UNA TRANSACCIÓN. 9

1. Consumo del Api REST para consultar

estado de pago. 9

EJEMPLOS CONSUMO Y RESPUESTA API

REST. 14

1. Ejemplo Json consumo inicio_pagoV2. 14

2. Ejemplo Respuesta consumo

inicio_pagoV2. 15

3. Ejemplo Json consumo Verificar_pagoV3. 15

4. Ejemplo Respuesta consumo

Verificar_pagoV3. 16

2. Pruebas manuales del WebService. 16

DIAGRAMAS. 17
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

Capítulo

1
INICIO Y FINALIZACIÓN DE
PAGOS.

1. Inicio de pago mediante

consumo del REST.
4 Mayo de 2011 se creó una nueva forma de conexión, a través de un Api REST
“api_inicio_pago” que cumple con toda la funcionalidad de monocrédito, multicrédito y
cumple con las nuevas reglas de certificación de enviar el tipo de documento. Este Api REST
cumple con los mismos campos que se usan para el ws_inicio_pago.

La ruta del Api REST de producción es la siguiente:

https://www.zonapagos.com/api_inicio_pago/api/inicio_pagoV2

La ruta del Api REST de Pruebas es la siguiente:

https://www.zonapagosdemo.com/api_inicio_pago/api/inicio_pagoV2

El método que se debe utilizar para este Api es:

POST

1
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

Los Valores que se deben enviar son:

Nombre Tipo y tamaño Descripción

id_tienda Numérico Identificador único del comercio.
Este valor es suministrado por
Obligatorio Zona Virtual.

clave Alfanumérico Clave de validación entre el

Tamaño comercio y ZonaPAGOS.
máximo: 50 Este parámetro es entregado por
caracteres. ZonaPAGOS al comercio y se
debe enviar cada que el comercio
quiera iniciar un pago en
Obligatorio ZonaPAGOS. (Puede ser
cambiado en el tiempo pero debe
ser sincronizado enter el comercio
y ZonaPAGOS)
total_con_iva Numérico Total a pagar con IVA incluido
Valor numérico, máximo 2
Obligatorio decimales.
valor_iva Numérico Total IVA
Valor numérico, máximo 2
Obligatorio decimales.
Si no se utiliza IVA, se debe
enviar cero.
Id_pago Numérico Identificador del pago, puede ser
Tamaño el número de factura o algún valor
máximo: 30 con el cual identificar el pago o
caracteres. transacción en el futuro.

Obligatorio
descripcion_pago Alfanumérico Concepto o descripción del pago
Tamaño que realizará el cliente
máximo: 70
caracteres.

Obligatorio
email Alfanumérico Correo del cliente, se sugiere
Tamaño enviar ya que si se utiliza, al final
máximo: 70 del pago el cliente recibe un
caracteres. correo con toda la información de
su pago.
Opcional

2
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

Id_cliente Alfanumérico Cédula, Nit o código de

Tamaño identificación del cliente que
máximo: 30 realizará el pago.
caracteres. NOTA: Para la certificación de
PSE, este campo es Obligatorio
Opcional
tipo_id Alfanumérico Tipo identificación del cliente (
Tamaño Los Valores que se deben enviar
máximo: 5 son:
caracteres. 0 No se usa o Tipo no
Identificado
Se envía el 1 CC Cedula de Ciudadanía
número 2 CE Cedula de Extranjería
equivalente al 3 NIT Nit Empresa
documento 4 NUIP Número Único de
Identificación
5 TI Tarjeta de Identidad
Opcional* 6 PP Pasaporte
*Depende de la 7 IDC Identificador Único del
configuración que Cliente
se especifique del
comercio
8 CEL En caso de que el
identificador sea un número móvil
o celular
9 RC Registro Civil de
Nacimiento
10 DE Documento de
Identificación Extranjero
11 Otro no tipificado

NOTA: Para la certificación de

PSE, este campo es Obligatorio
nombre_cliente Alfanumérico Nombre del cliente que realizará
Tamaño el pago.
máximo: 50
caracteres.

Opcional
apellido_cliente Alfanumérico Apellido del cliente que realizará
Tamaño el pago
máximo: 50
caracteres.

Opcional

3
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

telefono_cliente Alfanumérico Teléfono cliente.

Tamaño
máximo: 50
caracteres.

Opcional
info_opcional1 Alfanumérico Campo con información opcional
Tamaño 1
máximo: 70
caracteres.

Opcional
info_opcional2 Alfanumérico Campo con información opcional
Tamaño 2
máximo: 70
caracteres.

Opcional
info_opcional3 Alfanumérico Campo con información opcional
Tamaño 3
máximo: 70
caracteres.

Opcional
codigo_servicio_principal Numérico Caso Multicrédito
Es el código de servicio principal
Obligatorio o padre.
Caso Normal
Código de servicio estándar.

lista_codigos_servicio_multicredito
Importante
Este código de servicio debe
estar previamente creado tanto
en PSE como en Zona Pagos.
Arreglo o matriz Caso Multicrédito
unidimensional Contiene la lista de todos los
códigos de servicio multicrédito
hijos del código de servicio
Es obligatorio principal.
en caso de ser
multicrédito. Caso Normal
No se llena, se envía nulo este
parámetro.

4
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

Importante
Estos códigos de servicio
deben estar previamente
creados tanto en PSE como en
Zona Pagos

lista_nit_codigos_servicio_multicredito Arreglo o matriz Caso Multicrédito

unidimensional Contiene la lista de todos los Nit
correspondientes a los códigos de
Es obligatorio servicio multicrédito Enviados
en caso de ser
multicrédito. Caso Normal
No se llena, se envía nulo este
parámetro.

Importante
Estos códigos de servicio
deben estar previamente
creados tanto en PSE como en
Zona Pagos

lista_valores_con_iva Arreglo o matriz Caso Multicrédito

unidimensional Contiene la lista de todos los
valores a pagar de cada servicio
Es obligatorio multicrédito enviado.
en caso de ser Las suma de todos los valores
multicrédito. enviado debe ser igual al
parametro enviado “
total_con_iva”

Caso Normal
No se llena, se envía nulo este
parámetro.
lista_valores_iva Arreglo o matriz Caso Multicrédito
unidimensional Contiene la lista de los valores del
IVA a pagar de cada servicio
Es obligatorio multicrédito enviado.
en caso de ser Las suma de todos los valores
multicrédito. enviado debe ser igual al
parámetro enviado “valor_iva”. Si
no se maneja IVA se debe enviar
cero.

5
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

Caso Normal
No se llena, se envía nulo este
parámetro.
total_codigos_servicio Numérico Caso Multicrédito
Es la suma del número de códigos
Es obligatorio de servicio multicrédito que se
en caso de ser enviaron (Sin contar el código de
multicrédito. servicio principal)

Caso Normal
Se envía 0 (cero) este parámetro.

Si el consumo del Api REST fue exitoso, se devuelve un cadena que contiene un número
entero mayor 0, el cual es el identificador de la transacción el cual se debe utilizar para que el
comercio proceda a re direccionar al cliente que desea realizar el pago a la ruta:

https://www.zonapagos.com/t_ruta/pago.asp?estado_pago=iniciar_pago&identificador=911
15600000035023

El Valor “t_ruta” es un valor especificado por Zona Virtual y único para cada comercio.

El número 91115600000035023 es un ejemplo del identificador retornado por el Api REST.

Si se genero algún problema en el consumo y/o inicio de la transacción, se devuelve una

cadena que comienza con -1 luego un espacio, con la descripción del problema que ocurrió.

Ejemplo: -1 Parámetro id_pago contiene caracteres no permitidos.

6
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

2. Recepción de parámetros de
resultado del pago por GET
Al finalizar el pago se realizara un llamado (sea el pago fue exitoso o fallido) a una ruta en su
servidor, la cual el comercio nos deben especificar.

A esta ruta se enviara la siguiente información en formato GET

Nombre Variable Tipo Descripción

id_pago Numérico Aquí se envía el identificador del pago que se

envió a la pasarela al comienzo del proceso

estado_pago Numérico Se envía 1 si el pago se realizo OK, 0 (cero) o

Null si el pago no se pudo realizar.
id_forma_pago Numérico Se envía 4 que indica que el pago se realizo por
un banco ACH PSE
Se envía 5 indica que el pago se realizo por tarjeta
de crédito en línea
valor_pagado Numérico Se envía el valor que se pago en el banco

ticketID Numérico Se envía el identificador del pago ante el banco,

(este valor es el que aparece en él informe emitido
por ACH PSE para identificar el pago
id_clave Alfanumérico Es un valor que se debe utilizar para verificar que
el llamado se realizo desde el servidor indicado,
este valor se puede cambiar constantemente.
id_cliente Alfanumérico Es el identificador del cliente que inicio el pago,
normalmente la cedula, nit, carnet etc
Si no se utiliza o no se llena, se envía VACIO
franquicia Alfanumérico Si el pago se realizo con tarjeta de crédito en línea
se envía el nombre de la franquicia así:
VISA
Credencial Master Card
Diners Club
American ExpressVisa
Master Card

7
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

codigo_servicio Numérico Aplica Solo Medio de Pago PSE.

Retorna el código de Servicio, con el cual se inicio
la transacción.

codigo_banco Numérico Aplica Solo Medio de Pago PSE.

Retorna el código del banco desde donde el
cliente inicio el pago

nombre_banco Alfanumérico Aplica Solo Medio de Pago PSE.

Retorna el nombre del banco desde donde el
cliente inicio el pago

codigo_transaccion Numérico Aplica Solo Medio de Pago PSE.

Retorna el código único de transacción CUS

ciclo_transaccion Numérico Aplica Solo Medio de Pago PSE.

Retorna el ciclo de la transacción

campo1 Alfanumérico Retorna el campo opcional 1 que se envió cuando

se inicio la transacción
campo2 Alfanumérico Retorna el campo opcional 2 que se envió cuando
se inicio la translación
campo3 Alfanumérico Retorna el campo opcional 2 que se envió cuando
se inicio la transacción
idcomercio Numérico Es el identificador único del comercio definido
por ZonaPAGOS cuando se crea el comercio

8
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

Capítulo

2
VERIFICACIÓN O CONSULTA
DEL ESTADO DE UNA
TRANSACCIÓN.

1. Consumo del Api REST para

consultar estado de pago.
En este capítulo se explica la forma como se deben enviar los parámetros de
consumo al Api Rest de nuestro aplicativo para consultar un pago.

La ruta del Api REST de producción es la siguiente:

https://www.zonapagos.com/api_verificar_pagoV3/api/verificar_pago_v3

La ruta del Api REST de Pruebas es la siguiente:

https://www.zonapagosdemo.com/api_verificar_pagoV3/api/verificar_pago_v3

El método que se debe utilizar para este Api es:

POST

9
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

Este método debe ser usado para consultar información del pago de una transacción.

int verificar_pago_v3( string str_id_pago, int int_id_tienda, string str_id_clave, ref pagos_v3[]
res_pagos_v3, ref int int_error, ref string str_error )

Parámetros de Entrada
str_id_pago (string): se debe enviar el número único con el cual se inicio la transacción.
int_id_tienda (int): código único que asigna ZonaPAGOS al comercio para el manejo de las
transacciones.
str_id_clave (string): clave que asigna ZonaPAGOS al comercio y que corresponde a la
taquilla. La clave puede cambiar constantemente a solicitud del comercio.

Información de retorno
El método devolverá la cantidad de pagos encontrados en los estados:

888: Pago pendiente por iniciar.

999: Pago pendiente por finalizar.
1000: Pago rechazado
4000: Pago rechazado CR
4001: Pago pendiente
1: Pago finalizado Ok.

Si el numero retornado por el método en Contador_Pagos es Mayor a 0 (cero) se devolverá

por referencia el arreglo “res_pagos_v3” con la información del pago.
El método también devolverá por referencia lo siguiente:
int_error (int): devuelve un código de ejecución del Api.
-1: error inesperado o no diferenciado.
0: Se encontraron pagos.
1: No se encontraron pagos.
2: Comercio y/o clave inválida(s).
3: Se generó un error inesperado buscando el comercio y/o la clave.
str_error (string): Texto de mensaje según el código anterior.
-1: error inesperado o no diferenciado.
0: Se encontraron pagos.
1: No se encontraron pagos.
2: Comercio y/o clave inválida(s).
3: Se generó un error inesperado buscando el comercio y/o la clave.

Ejemplos:

Pago Exitoso
El método devuelve 1 (se encontró un pago).
En la variable “int_error” devuelve 0 (significa que se encontraron pagos).

10
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

En la variable “str_error” devuelve “Se encontraron pagos”.

En el arreglo “res_pago_v3” devuelve toda la información del pago y en la Variable
“int_estado_pago” se devuelve 1.

Pago Rechazado
El método devuelve 1 (se encontró un pago)
En la variable “int_error” devuelve 0 (significa que se encontraron pagos)
En la variable “str_error” devuelve “Se encontraron pagos”.
En el arreglo “res_pago_v3” devuelve toda la información del pago y en la Variable
“int_estado_pago” se devuelve 1000.

Pago Pendiente en Entidad Financiera

El método devuelve 1 (se encontró un pago).
En la variable “int_error” devuelve 0 (significa que se encontraron pagos).
En la variable “str_error” devuelve “Se encontraron pagos”.
En el arreglo “res_pago_v3” devuelve toda la información del pago y en la Variable
“int_estado_pago” se devuelve 999.

Pago Pendiente por la Central Antifraude (CA)

El método devuelve 1 (se encontró un pago).
En la variable “int_error” devuelve 0 (significa que se encontraron pagos).
En la variable “str_error” devuelve “Se encontraron pagos”.
En el arreglo “res_pago_v3” devuelve toda la información del pago y en la Variable
“int_estado_pago” se devuelve 4001.

Pago Pendiente por iniciar en Entidad Financiera

El método devuelve 1 (se encontró un pago)
En la variable “int_error” devuelve 0 (significa que se encontraron pagos)
En la variable “str_error” devuelve “Se encontraron pagos”
En el arreglo “res_pago_v3” devuelve toda la información del pago y en la Variable
“int_estado_pago” se devuelve 888.

Error de Clave o Comercio Inválido

El método devuelve 0 (NO se encontraron pagos para saber el motivo siempre interpretar
int_error)
En la variable “int_error” devuelve 2 (significa Comercio y/o clave inválida(s).)
En la variable “str_error” devuelve “Comercio y/o clave inválida(s).”
En el arreglo “res_pago_v3” No se devuelve Nada. (null).

Error no identificado
El método devuelve -1 (NO se encontraron pagos para saber el motivo siempre interpretar
int_error)
En la variable “int_error” devuelve -1 (significa error inesperado o no diferenciado.)

11
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

En la variable “str_error” devuelve “Comercio y/o clave inválida(s).”

En el arreglo “res_pago_v3” No se devuelve Nada. (null).

Detalle Arreglo “res_pagos_v3”

Arreglo de clases con la información disponible de una transacción.

Principalmente se debe evaluar el campo “int_estado_pago” el cual determina como se
encuentra el pago. Los datos que contiene el arreglo son los siguientes:

Variable Tipo Descripción

Identificador del pago que fue enviado por la
str_id_pago string
pasarela al iniciar el pago.
Estado actual del pago enviado por la
pasarela.
888: Pago pendiente por iniciar.
int_estado_pago Int
999: Pago pendiente por finalizar.
1: Pago finalizado Ok.

Se envía (29) si el pago fue realizado por PSE o (31

int_id_forma_pago Int o 32) si el pago fue realizado por tarjeta de crédito
en línea.
Se envía el valor que fue pagado por el cliente en el
dbl_valor_pagado Double
banco.
Se envía el identificador del pago ante el banco.
str_ticketID String Este es el valor emitido por PSE para identificar el
pago.
Se envía la clave que se utiliza para identificar que
el llamado de finalización se está realizando desde
str_id_clave String
el servidor de ZonaPAGOS. La clave se puede
cambiar en cualquier momento.
Es el identificador del cliente que inicio el pago. Si
str_id_cliente String
no se utiliza se envía vacío.
Si el pago se realizó con tarjeta de crédito en línea,
se envía el código de la franquicia usada por el
cliente, de la siguiente manera:
Credencial
str_franquicia String
Diners Club
American Express
Visa
Master Card
Código entregado por las franquicias. Sólo se
int_cod_aprobacion Int
utiliza en tarjeta de crédito en línea.
int_codigo_servico Int Se envía el código de servicio con el cual se inicio

12
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

la transacción. Sólo se utiliza en PSE.

Se envía el código del banco desde donde se inicio
int_codigo_banco Int el pago por parte del cliente. Sólo se utiliza en
PSE.
Se envía el nombre del banco desde donde se
str_nombre_banco String inicio el pago por parte del cliente. Sólo se utiliza
en PSE.
str_codigo_transacci Se envía el código único de la transacción generado
String
on por PSE. Sólo se utiliza en PSE.
int_ciclo_transaccio Se envía el ciclo en el cual quedó la transacción en
Int
n PSE. Sólo se utiliza en PSE.
Se envía lo enviado en el campo opcional 1 cuando
str_campo1 String
se inicio la transacción.
Se envía lo enviado en el campo opcional 2 cuando
str_campo2 String
se inicio la transacción.
Se envía lo enviado en el campo opcional 3 cuando
str_campo3 String
se inicio la transacción.
DateTi Fecha en la que se realizó la transacción según
dat_fecha
me PSE. No se debe tener en cuenta la hora.

13
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

Capítulo

3
EJEMPLOS CONSUMO Y
RESPUESTA API REST.
Se realizaron los ejemplos con el fin de dar una ayuda adicional al desarrollador
y conozca cómo se debería enviar el Json por el método POST en el Api
REST.

1. Ejemplo Json consumo

inicio_pagoV2.

"id_tienda": "180",
"clave": "TgfdZ435",
"total_con_iva": "10000",
"valor_iva": "0",
"id_pago": "363466",
"descripcion_pago": "Esto es una prueba",
"email": "soporte@zonavirtual.com",
"id_cliente": "123",
"tipo_id": "1",

14
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

"nombre_cliente": "Soporte",
"apellido_cliente": "Zona Virtual",
"telefono_cliente": "4449662",
"info_opcional1": "1",
"info_opcional2": "2",
"info_opcional3": "3",
"codigo_servicio_principal": "2701",
"lista_codigos_servicio_multicredito": "NULL",
"lista_nit_codigos_servicio_multicredito": "NULL",
"lista_valores_con_iva": "NULL",
"lista_valores_iva": "NULL",
"total_codigos_servicio": "0",
}

2. Ejemplo Respuesta consumo

inicio_pagoV2.
"7675420000016345"

3. Ejemplo Json consumo

Verificar_pagoV3.
{
"str_id_pago":"332507",
"int_id_tienda":"180",
"str_id_clave":"TgfdZ435"
}

15
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

4. Ejemplo Respuesta consumo

Verificar_pagoV3.
{
"Contador_Pagos": 1,
"res_pagos_v3": [ {
"str_id_pago": "332507",
"int_estado_pago": 1,
"int_id_forma_pago": 29,
"dbl_valor_pagado": 614200,
"str_ticketID": "33250700188",
"str_id_clave": "TgfdZ435",
"str_id_cliente": "555555",
"str_franquicia": "",
"int_cod_aprobacion": 0,
"int_codigo_servico": 1234,
"int_codigo_banco": 1022,
"str_nombre_banco": "Banco Union Colombiano",
"str_codigo_transaccion": "856448",
"int_ciclo_transaccion": 1,
"str_campo1": "",
"str_campo2": "",
"str_campo3": "",
"dat_fecha": "2013-11-15T14:56:59"
}],
"int_error": 0,
"str_error": "Se encontraron pagos. los parametros recibido fueron
id_tienda:180id_clave:TgfdZ435id_pago:332507"
}

2. Pruebas manuales del

WebService.
En la ruta:
https://www.zonapagos.com/prueba_ws_verificar_pagos/prueba_ws_verificar_pagos.aspx,
puede hacer todas las consultas que desee en forma manual o para verificar que el desarrollo de
la sonda está correcto.

16
 ZP-A-021 - INT
Pasarela de pagos versión REST
Versión 1.0

Capítulo

2
4
DIAGRAMAS.

17