CyberPAG. Documentacion de API.

CyberPAG ofrece a los desarrolladores que deseen integrar una solucin de comercio
electrnico con sus sistema de pagos una interfaz REST JSON para comunicarse con dicho
sistema.
El objetivo de este documento es definir los parmetros de comunicacin con dicha interfaz as
como describir los formatos de respuesta que CyberPAG enviar a la solucin de comercio
electrnico en el caso de informes, pagos aceptados o pagos rechazados.

Comunicacin comercio - interfaz

El punto de acceso de la interfaz es:
https://tpv.cyberpag.com/tpv.php
El nico mtodo HTTP disponible en dicho punto de acceso es POST.
Todas las llamadas a dicho punto de acceso deben realizarse con un parmetro de entrada que
ser un objeto JSON que contar con los atributos necesarios para ejecutar la accin
requerida.
A continuacin se listan todas las posibles acciones que permite la interfaz, junto con la
definicin de sus parmetros de entrada y de sus parmetros de salida.

Enviar pago
El objeto JSON de entrada seguir el siguiente formato:
{
action: string,
user: string,
key: string,
amount: number,
currency: string,
subject: string
}
Descripcin:

action: accin que se desea ejecutar. Cadena constante send-order.

user: nmero de comercio integrado en CyberPAG.
key: clave de API del comercio integrado en CyberPAG.
amount: cantidad del importe.
currency: cdigo ISO 4217 de la divisa del importe. Cadena constante PEN. No
estn permitidas otras divisas.
subject: concepto del importe. Parmetro opcional.

La respuesta del mtodo ser un objeto JSON con la siguiente estructura:

{
url: string,
secret: string,
token: string
}
Dnde:

url: es la URL a la que debe redireccionar el comercio para finalizar el pago.

secret: es una cadena de texto que el comercio debe almacenar y enlazar con el
pedido actual.
token: es una cadena de texto que identifica el pedido actual.

A partir de aqu, el comercio debe realizar dos acciones de suma importancia:

1. Almacenar el valor del campo secret y el valor del campo token, ya que sern los
utilizados por la pasarela para identificar el pedido cuando realice las comunicaciones
a la URL OK, KO y REPORT del comercio. Adems, deber enlazarlos con el pedido
actual, de tal manera que el comercio pueda recuperar el pedido a partir del campo
secret y token.
2. Redireccionar a la URL proporcionada. El usuario ser dirigido a una pantalla de
CyberPAG donde podr identificarse y elegir su mtodo de pago para, finalmente,
confirmar el pago. Una vez hecho esto, CyberPAG har una llamada a la URL OK del
comercio con el cdigo 202, tal y como se explica en la siguiente seccin.

Comunicacin interfaz comercio

Hay cinco posibles casos en los que la interfaz puede comunicarse con la solucin de comercio
electrnico integrada en CyberPAG:
1. Cuando se solicita un pago, haciendo una llamada a la URL OK definida durante la
integracin del comercio.
2. Cuando se ejecuta un pago, haciendo una llamada a la URL OK definida durante la
integracin del comercio.
3. Cuando se deniega un pago, haciendo una llamada a la URL KO definida durante la
integracin del comercio.
4. Cuando se cancela un pago, haciendo una llamada a la URL KO definida durante la
integracin del comercio.
5. Cuando un pago cambia a algn estado no definido en los puntos anteriores, haciendo
una llamada a la URL REPORT definida durante la integracin del comercio.
En el caso 1, cuando se solicita un pago, la llamada a la URL OK se realiza a travs del mtodo
GET de HTTP con un nico parmetro, token, que contendr el token que hace referencia al
pedido. El comercio deber marcar el pedido como pendiente de pago.
En los restantes casos, la interfaz realizar una llamada POST a la URL indicada, con el campo
Content-Type de la cabecera al valor application/json, conteniendo como parmetro un objeto
JSON que seguir el siguiente formato:

{
code: number,
date: string,
secret: string
}
Dnde:

code: es un cdigo numrico que identifica el tipo de informe enviado. Se describen

ms adelante.
date: fecha y hora en formato ISO 8601 (YYYY-MM-DDTHH:MM:SS) del informe.
secret: es una clave que identifica al pedido. El comercio debe comprobar que dicha
clave se corresponde con que la que tiene almacenada con el objetivo doble de
verificar que se trata de una comunicacin segura y de identificar el pedido al que se
refiere dicha comunicacin.

Cdigos
Se describen a continuacin los posibles cdigos de respuesta de la interfaz, cuando se realiza
a travs del mtodo POST, junto la URL a la que se llama y una pequea descripcin de su
significado. Es responsabilidad del comercio realizar las modificaciones necesarias respecto al
estado del pedido referenciado para cada uno de los diferentes casos.
200

100

301

302

Nombre: pago efectuado.

URL: URL OK.
Descripcin: el cliente ha efectuado el pago del pedido referenciado por su clave
secreta en alguna de las modalidades permitidas por CyberPAG y el dinero ya se
encuentra en la cuenta del vendedor.

Nombre: aviso de proximidad de vencimiento de pago.

URL: URL REPORT.
Descripcin: la fecha de fin de pago para el pedido referenciado por su clave secreta
est a punto de vencer.

Nombre: pago caducado.

URL: URL KO.
Descripcin: ha vencido la fecha de fin de pago para el pedido referenciado por su
clave secreta.

Nombre: pago denegado.

URL: URL KO.
Descripcin: el pago del pedido referenciado por su clave secreta ha sido denegado
bien por la entidad bancaria o bien por CyberPAG.

303

Nombre: pago cancelado.

URL: URL KO.
Descripcin: el pago del pedido referenciado por su clave secreta ha sido cancelado
bien por el propio cliente o bien por CyberPAG.