VTOL Payment Bridge

Manual de Integración

Cambios por revisiones

Índice

1. Introducción

1.1 Acerca de este documento

El presente documento explica la forma en la que un e-commerce se puede integrar con VTOL Payment Bridge, para autorizar pagos a través de Internet.

1.2 ¿Qué es VTOL Payment Bridge?

Es un componente Web que permite a un sitio de e-commerce autorizar contra VTOL Server los pagos de compras realizadas con tarjeta en Internet. 

Cuando el cliente del e-commerce quiera pagar su compra con tarjeta se hace una redirección segura hacia VTOL Payment Bridge, quién solicita los datos para efectuar el pago.
A continuación se muestra una imagen del formulario que solicita los datos para efectuar el pago con tarjeta.

Formulario de pago de VTOL Payment Bridge

1.3 Ventajas

Algunas de las ventajas de usar VTOL Payment Bridge son:

1. Velocidad de integración con VTOL
2. Evitar implementar un formulario de ingreso de datos de tarjetas y sus correspondientes validaciones
3. Cumplir con las normas PCI ya que el e-commerce no tiene conocimiento de los datos sensibles de la tarjeta
4. Simplificar la conciliación con VTOL

1.4 Arquitectura

Como se observa en la figura, VPB recibe la petición de autorización del browser del cliente, con los datos de venta del e-commerce. Entre esos datos viaja el identificador de transacción generado por el e-commerce (transactionId).
VPB por su parte despliega una ventana segura para cargar los datos de la tarjeta. Una vez completados los datos, autoriza la transacción contra VTOL Server y responde a una dirección de callback, incluyendo el transactionId enviado en el requerimiento de autorización.
El e-commerce es quien posteriormente debe realizar la consulta del estado de la transacción pasando como parámetro su identificador en una invocación GET a VPB.
Por último y una vez que finalizó la operación con el cliente, el e-commerce realiza una invocación POST a VPB indicando la confirmación o cancelación de la transacción. VPB al recibir el requerimiento de confirmación o cancelación, envía un Commit o Rollback a VTOL Server.

1.5 Alcance

1.5.1 VTOL Payment Bridge

1. Proveer un marco de intercambio de información seguro para evitar ataques y fraudes. Utilización de protocolo https.
2. Autorizar mediante VTOL Server las transacciones de pago con tarjeta en Internet.
3. Facilitar los datos de transacciones autorizadas.
4. Brindar un mecanismo de conciliación entre el e-commerce y VTOL Server.

1.5.2 E-Commerce

1. Utilización de protocolo seguro https.
2. Encriptar los datos que se envían a VPB en la invocación de autorización.
3. Consultar a VPB el estado y datos de la transacción autorizada.
4. Indicar a VPB si debe confirmar o cancelar la transacción.
5. Brindar a VPB información sobre confirmación o cancelación de una transacción cuando este lo requiera, mediante una invocación GET.

1.6 Alta disponibilidad

La versión actual de VTOL Payment Bridge no soporta alta disponibilidad. Es decir, que la aplicación actualmente está construida para trabajar como un nodo único.

2. Instalación

2.1 Servidor Web

VTOL Payment Bridge es una aplicación pensada para ser integrada en el contenedor Web de Apache Tomcat versión 9.

Descargas en: http://tomcat.apache.org/download-60.cgi

2.2 Requerimientos mínimos

A continuación se detallan los requerimientos mínimos que son requeridos para poder instalar y ejecutar la aplicación.

Hardware

Software

2.3 Instalación

La instalación de VTOL Payment Bridge consiste básicamente en incluir la carpeta que conforma la aplicación dentro del contenedor Web y configurar los archivos necesarios para lograr un intercambio de información segura. 

La entrega es básicamente en un archivo ZIP. Al descomprimirse se obtiene la siguiente estructura de carpetas:

2.4 Configuración Contenedor Web

2.4.1 Protocolo Seguro HTTPS

Es requisito fundamental configurar la transferencia por protocolo seguro.

Primero: se debe realizar la siguiente configuración en el archivo \conf\server.xml de Tomcat.

• Descomentar y configurar el conector HTTPS

Es necesario configurar el conector de protocolo seguro agregando el archivo que contiene el certificado, así como también los cifrados utilizados.

El archivo synthesis.keystore es el almacén de claves que contiene el certificado para lograr transporte seguro. Se encuentra disponible en la carpeta /vtolPaymentBridge/conf/ y debe ser copiado a la carpeta /conf del contenedor Web.

• Comentar la línea AprLifecycleListener

Segundo: Agregar configuración de cookies en el archivo \conf\context.xml de Tomcat

Configurar las cookies de sesión secure y httpOnly

2.4.2 Conexión con Base de Datos

La conexión con base de datos se configura en el archivo \conf\context.xml de Tomcat, agregando el recurso datasource "jdbc/RSVTOL" de la siguiente manera:

Ejemplo Oracle

Ejemplo MSSQL

2.5 Creación de Base de Datos

Se debe crear la base de datos para la aplicación y contar con usuario que tenga permisos de OWNER sobre la misma. Luego con dicho usuario se deben ejecutar los scripts para crear y popular la base de datos. Los archivos scripts se encuentran disponibles en la carpeta \vtolpaymentBridge\scripts. 

El usuario OWNER será el que se utilice para conectar la aplicación.

3. Integración

En esta sección se detalla la manera de integrar el e-commerce con VTOL Payment Bridge.

3.2 Servicios brindados por VPB

VTOL Payment Bridge brinda los siguientes servicios:

3.2.1 Solicitud de Pago

Para realizar solicitud de Pago el browser del cliente debe hacer una invocación POST a la URL de VPB.

En la invocación se envía el parámetro data con los datos de la venta del e-commerce.

El parámetro data está formado por una serie de campos respetando el siguiente formato:

Nombre del campo=valor

Para separar los campos se utiliza el separador | (pipe)

Ejemplo:
$data="amount=10000|transactionId=2014022420301200001|[email protected]|[email protected]|callbackErrorURL=http:///200.12.3.45/e-commerce/resulterror.jsp|callbackOKURL= http:///200.12.3.45/e-commerce/resultok.jsp|payments=1|currency=$|plan=0|nombre=Jose|apellido=Perez|localidad=|domicilio=|provincia=|pais=|ipAdress=200.100.24.35";

Los campos que forman parte del parámetro data se detallan a continuación:

3.2.2 Consulta de estado transacción

VPB permite consultar el estado y los datos de una autorización, a través de una invocación GET a la URL: ¡Error! Referencia de hipervínculo no válida.
La invocación se realiza enviando el parámetro data que incluye el campo transaccionId encriptado. El cual se envía con el siguiente formato: transactionId=<valor>

Ejemplo de invocación GET con el campo ya encriptado:

https://192.168.0.119:8443/web-vtol/service/checkTransactionStatus.html?data=FjfjyNklPe01RHOiXLpTxG30H6wBGXOb


La respuesta de la invocación GET devuelve directamente los siguientes campos encriptados:

Para separar los campos se utiliza el separador | (pipe)

3.2.3 Cierre de Transacción

VPB permite cerrar la transacción para confirmarla o cancelarla, a través de un método POST a la URL:

La invocación a este servicio se realiza enviando el parámetro data, conteniendo los siguientes campos encriptados:

3.3 Mensajes brindados por el E-Commerce

El e-commerce debe brindar la posibilidad de realizar la consulta de estado de la transacción, para que VPB pueda consultar si debe confirmar o cancelar la operación contra VTOL Server, en caso de producirse alguna desincronización de estados.

3.3.1 Consulta de estado transacción

Se debe poder realizar una invocación GET a una URL especifica del e-commerce, pasando el parámetro data que contiene el campo transactionId encriptado. El cual se envía con el siguiente formato: transactionId=<valor>
VPB debe conocer la URL del servicio para poder realizar la consulta.

Ejemplo de invocación con el dato encriptado:

http://www.e-commerce/checkStatus.php?data=FjfjyNklPe01RHOiXLpTxG30H6wBGXOb

La respuesta a dicha invocación GET debe incluir los siguientes campos encriptados:

Para separar los campos se utiliza el separador | (pipe)

Ejemplo:
transactionId=697900|status=Commit

3.4 Códigos de Respuesta

VPB responde a cada transacción que recibe para autorizar con un código de respuesta y una descripción del mismo, indicando cual fue el resultado de la operación. 

A continuación se detallan las respuestas posibles.

3.4.1 Códigos recibidos de VTOL Server

Nota: La respuesta con código '099' representa un error en el procesamiento interno de VTOL, independientemente de la interacción con el Centro Autorizador

Códigos de respuesta por validación en VPB