VTOL Payment Bridge
Manual de Integración
Cambios por revisiones
Fecha | Revisión | Cambios – Motivo |
06/01/2014 | 1.0 | Creación del documento |
08/08/2014 | 1.1 | Requerimientos mínimos |
08/09/2015 | 1.2 | Agregado de aclaraciones |
21/02/2019 | 1.3 | Revisión y actualización de la documentación |
Índice
Índice
Âncora _Toc434487091 _Toc434487091
1. Introducción
_Toc434487091 | |
_Toc434487091 |
Âncora _Toc434487092 _Toc434487092
1.1 Acerca de este documento
_Toc434487092 | |
_Toc434487092 |
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.
Âncora _Toc434487093 _Toc434487093
1.2 ¿Qué es VTOL Payment Bridge?
_Toc434487093 | |
_Toc434487093 |
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
Âncora _Toc434487094 _Toc434487094
1.3 Ventajas
_Toc434487094 | |
_Toc434487094 |
Las ventas Algunas de las ventajas de usar VTOL Payment Bridge son:
- Velocidad de integración con VTOL
- Evitar implementar un formulario de ingreso de datos de tarjetas y sus correspondientes validaciones.
- Cumplir con las normas PCI ya que el e-commerce no tiene conocimiento de los datos sensibles de la tarjeta
- Simplificar la conciliación con VTOLEtc
Âncora _Toc434487095 _Toc434487095
1.4 Arquitectura
_Toc434487095 | |
_Toc434487095 |
Como se observa en la figura, VPB recibe la petición de autorización del browser del cliente, con los datos previamente encriptados por el 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 la el requerimiento de confirmación o cancelación, envía un Commit o Rollback a VTOL Server.
Aviso |
---|
Importante: Todas las invocaciones realizadas se encuentran sobre protocolo seguro HTTPS. |
Âncora _Toc434487096 _Toc434487096
1.5 Alcance
_Toc434487096 | |
_Toc434487096 |
Âncora _Toc434487097 _Toc434487097
1.5.1 VTOL Payment Bridge
_Toc434487097 | |
_Toc434487097 |
- Proveer un marco de intercambio de información seguro para evitar ataques y fraudes. Utilización de protocolo https.
- Autorizar mediante VTOL Server las transacciones de pago con tarjeta en Internet.
- Facilitar los datos de transacciones autorizadas.
- Brindar un mecanismo de conciliación entre el e-commerce y VTOL Server.
Âncora _Toc434487098 _Toc434487098
1.5.2 E-Commerce
_Toc434487098 | |
_Toc434487098 |
- Utilización de protocolo seguro https.
- Encriptar los datos que se envían a VPB en la invocación de autorización.
- Consultar a VPB el estado y datos de la transacción autorizada.
- Indicar a VPB si debe confirmar o cancelar la transacción.
- Brindar a VPB información sobre confirmación o cancelación de una transacción cuando este lo requiera, mediante una invocación GET.
Âncora _Toc434487099 _Toc434487099
1.6 Alta disponibilidad
_Toc434487099 | |
_Toc434487099 |
La versión actual de VPB VTOL Payment Bridge no soporta alta disponibilidad. Es decir, que la aplicación actualmente está construida para trabajar como un nodo único.
Âncora _Toc434487100 _Toc434487100
2. Instalación
_Toc434487100 | |
_Toc434487100 |
Âncora _Toc434487101 _Toc434487101
2.1 Servidor Web
_Toc434487101 | |
_Toc434487101 |
VTOL Payment Bridge es una aplicación pensada para ser integrada en el contenedor Web de Apache Tomcat versión 69.
Descargas en: http://tomcat.apache.org/download-60.cgi
Âncora _Toc434487102 _Toc434487102
2.2 Requerimientos mínimos
_Toc434487102 | |
_Toc434487102 |
A continuación se detallan los requerimientos mínimos que son requeridos para poder instalar y ejecutar la aplicación.
Hardware
Componente | Requerimiento Mínimo |
Memoria RAM | Mínimo de 1 GB disponible para la aplicación |
Disco Rígido | Mínimo de 1 GB disponible para la aplicación |
Software
Componente | Requerimiento Mínimo |
Sistema Operativo |
|
Máquina Virtual | JVM SUN 1.68.xX de 32bits o 64bits |
Contenedor Web | Tomcat versión 69 |
Base de datos | MSSQL 2000, 2005 2008 o 2008superior |
Âncora _Toc434487103 _Toc434487103
2.3 Instalación
_Toc434487103 | |
_Toc434487103 |
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:
Carpeta | Descripción |
conf | Contiene archivos de configuración que deben ser copiados al contenedor Web:
|
lib | Contiene la librería con el driver de base de datos que debe ser copiado en la carpeta /lib del contenedor. |
scripts | Contiene los scripts para crear y popular la base de datos que utiliza la aplicación. |
vtolweb | Es la aplicación VPB. La carpeta debe ser copiada al directorio /webapps del contenedor Web. |
Âncora _Toc434487104 _Toc434487104
2.4 Configuración Contenedor Web
_Toc434487104 | |
_Toc434487104 |
Âncora _Toc434487105 _Toc434487105
2.4.1 Protocolo Seguro HTTPS
_Toc434487105 | |
_Toc434487105 |
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.
<!-- Define a SSL HTTP/1.1 Connector on port 8443 |
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
<!--APR library loader. Documentation at /docs/apr.html |
Segundo: Agregar configuración de cookies en el archivo \conf\context.xml de Tomcat
Configurar las cookies de sesión secure y httpOnly
<!-- The contents of this file will be loaded for each web application --> |
Âncora _Toc434487106 _Toc434487106
2.4.2 Conexión con Base de Datos
_Toc434487106 | |
_Toc434487106 |
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:
<!-- Datasource Connection --> |
Variable | Descripción |
[name] | Nombre del usuario de base de datos. |
[password] | Contraseña para el usuario de base de datos configurado en [name] |
[dbdriver] | Driver de conexión correspondiente al motor de base de datos utilizado. Oracle: oracle.jdbc.driver.OracleDriver MSSQL: net.sourceforge.jtds.jdbc.Drive La librería que contiene el driver se encuentra disponible en la carpeta /vtolPaymentBridge/lib y debe ser copiada a la carpeta /lib del contenedor Web. |
[dburl] | URL de conexión con la base de datos. |
Ejemplo Oracle
|
Ejemplo MSSQL
|
Âncora _Toc434487107 _Toc434487107
2.5 Creación de Base de Datos
_Toc434487107 | |
_Toc434487107 |
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.
Âncora _Toc434487108 _Toc434487108
3. Integración
_Toc434487108 | |
_Toc434487108 |
En esta sección se detalla la manera de integrar el e-commerce con VTOL Payment Bridge.
Âncora _Toc381043092 _Toc381043092
Âncora _Toc434487109 _Toc434487109
3.1 Clave de encriptación
_Toc381043092 | |
_Toc381043092 |
_Toc434487109 | |
_Toc434487109 |
Los datos enviados hacia y desde VPB, además de viajar sobre un protocolo seguro, se encuentran encriptados. Para poder realizar la tarea de encriptar y desencriptar los datos intercambiados, el e-commerce debe tener la capacidad de conocer y registrar la clave utilizada. Esta clave se brindará por el equipo de soporte en el momento de integración.
Âncora _Toc381043093 _Toc381043093
Âncora _Toc434487110 _Toc434487110
3.2 Servicios brindados por VPB
_Toc381043093 | |
_Toc381043093 |
_Toc434487110 | |
_Toc434487110 |
VTOL Payment Bridge brinda los siguientes servicios:
Âncora _Toc381043094 _Toc381043094
_Toc381043094 | |
_Toc381043094 |
...
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.
¡Error! Referencia de hipervínculo no válida.
Notar que la URL es sobre protocolo seguro HTTPS. |
En la invocación se envía el parámetro data con los datos previamente encriptados por el e-commerce, utilizando la clave que provee VTOL Payment Bridge.
<html> <body> <form id="authorize" name="authorize" action="http://10.4.14.56:8080/web-vtol/service/authorizeForm.html" method="post"> <input type="hidden" name="data" id="data" value="Ea95Qgome2fVUpqulzWW1ic965A1YwIkbqbceuaSapnHljO0bs1tdUEi66Vo2XrdzDZ3mZ9AcUlZVt+f9lESVTKgG2RTn+OSeKLcfTdnO+XALjW2M9G/SYC9FlGlBjhB8XMHkxIxdFZwWafiP7nu9PIxl7sIFo9TIaUcuxtH7VV9sAneBTBxsw+I/8yDd2ZQZr45IYGFGhDIAZ5ThSAHxKOEfRxO8TbXQf6FNSlOA1RotxqKSwKzrwG7qJrEWPvTob+8FFrmKgrbzWwOsxPiMFuwW50RycJAjGUP3lj+x/LNRiHXehwbuPTnq/jIXeXSiTCbYvOuC16NMyhmIVHuGrtzZLhGVfq07jkWw6aRIDD3CT5duNCosuCJx33oG7wMPWomR/4WI/ZgY44J0Sy5qmxGVsqEjFBMfYsc6xtW3LFQYaWiX2qcRAf8wHCYQsrn91t0UfVhQ29XHgL7DgvBu4GgD0oXuOiSvQFjSOxD2i0="/> <form> <script type="text/javascript"> document.authorize.submit(); </script> </body> </html> |
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:
Campo | Tipo | Obligatorio | Descripción |
amount | Numérico | Obligatorio | Importe total a pagar |
transactionId | Numérico | Obligatorio | Identificador de la transacción de pago. 16 dígitos de longitud. Debe ser generado por el e-commerce de manera tal que identifique unívocamente a una operación de pago, respetando el siguiente formato: yyyyMMddHHmmssxx, donde: yyyyMMddHHmmss: Fecha en que se realiza la operación con 4 dígitos para el año, 2 dígitos para el mes, 2 dígitos para el día, dos dígitos para la hora, dos dígitos para los minutos y 2 dígitos para los segundos. xx: 2 dígitos para el trace de transacciones. Es un valor incremental que inicia en 01 y su valor máximo es 99. |
currency | Alfanumérico | Obligatorio | Tipo de Moneda: $ = Pesos U$S = Dólares |
payments | Numérico | Obligatorio | Cantidad de cuotas. Valor constante 1. |
plan | Alfanumérico | Obligatorio | Plan. Valor constante 0. |
callbackErrorURL | Alfanumérico | Obligatorio | URL de respuesta que será invocada por VPB cuando el requerimiento genera un error de validación o se produce algún problema interno. En la invocación se envía el transaccionID correspondiente y un mensaje que detalla el error ocurrido. |
callbackOKURL | Alfanumérico | Obligatorio | URL de respuesta que será invocada por VPB cuando el requerimiento pudo ser enviado sin problemas al VTOL Server. En la invocación se envía el transacciónID correspondiente. |
userID | Alfanumérico | Opcional | Dirección de correo electrónico del cliente que realiza el pago. |
soporteID | Alfanumérico | Opcional | Dirección de correo electrónico del e-commerce. |
nombre | Alfanumérico | Opcional | Nombre del cliente que realiza el pago. |
apellido | Alfanumérico | Opcional | Apellido del cliente que realiza el pago. |
pais | Alfanumérico | Opcional | País al que pertenece el cliente. |
localidad | Alfanumérico | Opcional | Localidad en la que vive el cliente. |
provincia | Alfanumérico | Opcional | Provincia o estado donde vive el cliente |
domicilio | Alfanumérico | Opcional | Domicilio del cliente |
ipAdress | Alfanumérico | Obligatorio | Dirección IP del cliente. |
Âncora _Toc381043095 _Toc381043095
_Toc381043095 | |
_Toc381043095 |
...
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:
Campo | Tipo | Descripción |
responseCode | Numérico | Código de Respuesta de la transacción. Ver sección Códigos de Respuesta. |
message | Alfanumérico | Descripción del Código de Respuesta |
status | Alfanumérico | Estado de la transacción. Puede ser: Initialized: Inicializada Cancel: Cancelada por el usuario. Authorize: autorizando Rejected: rechazada Pending: Pendiente de confirmación. Commit: Confirmada Rollback: Cancelada. |
node | Numérico | Código de nodo de VTOL Server utilizado para la autorización. |
transactionId | Numérico | Identificador de la transacción. |
amount | Numérico | Importe total de la operación. |
currency | Alfanumérico | Tipo de moneda. |
ticket | Numérico | Ticket generado en VTOL Server |
authorizationCode | Numérico | Código de autorización de la transacción, en caso de que haya sido aprobada. |
vtolTrxId | Numérico | Identificador de la transacción en VTOL Server. |
providerCode | Alfanumérico | Código de autorizador. Ejemplo: Banamex |
displayMessage | Alfanumérico | Mensaje adicional enviado por el autorizador y que debe ser visualizado. |
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:
¡Error! Referencia de hipervínculo no válida.
La invocación a este servicio se realiza enviando el parámetro data, conteniendo los siguientes campos encriptados:
Campo | Tipo | Obligatorio | Descripción |
transactionId | Numérico | Obligatorio | Identificador de la transacción. |
action | Alfanumérico | Obligatorio | Commit: Confirmada Rollback: Cancelada. |
Âncora _Toc381043096 _Toc381043096
Âncora _Toc434487111 _Toc434487111
3.3 Mensajes brindados por el E-Commerce
_Toc381043096 | |
_Toc381043096 |
_Toc434487111 | |
_Toc434487111 |
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.
Âncora _Toc381043097 _Toc381043097
_Toc381043097 | |
_Toc381043097 |
...
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:
Campo | Tipo | Descripción |
status | Alfanumérico | Estado de la transacción. Puede ser: Commit: Confirmada Rollback: Cancelada. |
transactionId | Numérico | Identificador de la transacción. |
Para separar los campos se utiliza el separador | (pipe)
Ejemplo:
transactionId=697900|status=Commit
Âncora _Códigos_de_respuesta _Códigos_de_respuesta
Âncora _Toc434487112 _Toc434487112
3.4 Códigos de Respuesta
_Códigos_de_respuesta | |
_Códigos_de_respuesta |
_Toc434487112 | |
_Toc434487112 |
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
Código | Descripción |
'000' | Aprobada |
'001' | Pedir autorización telefónica |
'002' | Pedir autorización |
'003' | Comercio inválido |
'004' | Capturar tarjeta |
'005' | Denegada |
'007' | Retenga y llame |
'011' | Aprobada |
'012' | Transacción inválida |
'013' | Monto inválido |
'014' | Tarjeta inválida |
'025' | No existe original |
'030' | Error en formato |
'038' | Excede ingreso de PIN |
'043' | Retener tarjeta |
'045' | No opera en cuotas |
'046' | Tarjeta no vigente |
'047' | PIN requerido |
'048' | Excede máximo de cuotas |
'049' | Error fecha de vencimiento |
'050' | Entrega supera límite |
'051' | Fondos insuficientes |
'053' | Cuenta inexistente |
'054' | Tarjeta vencida |
'055' | PIN incorrecto |
'056' | Tarjeta no habilitada |
'057' | Transacción no permitida |
'058' | Servicio inválido |
'061' | Excede límite |
'065' | Excede límite de tarjeta |
'076' | Llamar al emisor |
'077' | Error plan/cuotas |
'085' | Aprobada |
'086' | No envía fecha original |
'089' | Terminal inválida |
'091' | Emisor fuera de línea |
'094' | Número de secuencia duplicado |
'095' | Re-transmitiendo |
'096' | Error en sistema |
'098' | No aprobada |
'099' | Error no clasificado |
Modo de ingreso inválido | |
Proveedor inválido | |
Error CVC | |
Error creando mensaje | |
Tipo de mensaje inválido | |
No envía código de autorización | |
Error en fecha efectiva | |
Error en fecha vencimiento | |
Tarjeta no efectiva | |
No opera off-line | |
Devolución monto mayor | |
Original ya anulada | |
Original ya devuelta | |
Original reversada | |
Moneda inválida | |
No envía fecha | |
Campo 71 inválido | |
Campo 71 nulo | |
CVC inválido | |
Terjeta inválida | |
Track2 inválido | |
No envía moneda | |
No envía CVC | |
Timeout | |
Fecha original inválida | |
No envía ticket original | |
Ticket original inválido | |
No envía código de autorización de venta referida | |
Reintente |
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.
Código | Descripción |
'100' | Iniciada |
'101' | TransactionId duplicado. |
'102' | No informó monto |
'103' | No informó moneda |
'104' | Autorizando |
'105' | VTOL Server no responde |
'106' | Error Interno VPB |
'107' | No Informa URL OK |
'108' | No Informa URL ERROR |
'109' | Transacción No Existe |
'110' | No Informa Plan |
'111' | No Informa Payments |