Versões comparadas

Versão antiga 3

changes.mady.by.user Usuário desconhecido (melodym)

Gravado em

comparado com

Nova versão 4

changes.mady.by.user Usuário desconhecido (juanc)

Gravado em

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

...

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/20191.3Revisión y actualización de la documentación



Índice


Índice



Âncora
_Toc434487091
_Toc434487091
1. Introducción

Âncora
_Toc434487092
_Toc434487092
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.


Âncora
_Toc434487093
_Toc434487093
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. 

...

Formulario de pago de VTOL Payment Bridge


Âncora
_Toc434487094
_Toc434487094
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


Âncora
_Toc434487095
_Toc434487095
1.4 Arquitectura

Image RemovedImage Added

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 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 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

Âncora
_Toc434487097
_Toc434487097
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.


Âncora
_Toc434487098
_Toc434487098
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.


Âncora
_Toc434487099
_Toc434487099
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.


Âncora
_Toc434487100
_Toc434487100
2. Instalación

Âncora
_Toc434487101
_Toc434487101
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


Âncora
_Toc434487102
_Toc434487102
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.

...

Componente

Requerimiento Mínimo

Sistema Operativo

  • Windows 8 64bits o superior, compatible con la versión de Java
  • Linux Debian u otra distribución compatible con Tomcat

Máquina Virtual

JVM SUN 1.8.X de 64bits

Contenedor Web

Tomcat versión 9

Base de datos

MSSQL 2008 o superior


Âncora
_Toc434487103
_Toc434487103
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. 

...

Carpeta

Descripción

conf

Contiene archivos de configuración que deben ser copiados al contenedor Web:

  • Synthesis.keystore: almacén de claves utilizado para transporte seguro HTTPS. Se debe copiar en la carpeta /conf del contenedor.

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

Âncora
_Toc434487105
_Toc434487105
2.4.1 Protocolo Seguro HTTPS

Es requisito fundamental configurar la transferencia por protocolo seguro.

...

<!-- The contents of this file will be loaded for each web application -->
<Context cookies="true" crossContext="true">
<!-- Session persistence is disable by default. To enable for all web
apps set the pathname to a non-empty value:
<Manager pathname="SESSIONS.ser" />

To enable session persistence for a single web app, add a
WEB-INF/context.xml
-->
<Manager pathname="" />

<SessionCookie secure="true" httpOnly="true" path="/" />

<!-- Install an InstanceListener to handle the establishment of the run-as
role for servlet init/destroy events.
-->
<InstanceListener>org.jboss.web.tomcat.security.RunAsListener</InstanceListener>

</Context>


Âncora
_Toc434487106
_Toc434487106
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:

...


<!-- Datasource Connection -->
<Resource name="jdbc/RSVTOL" auth="Container" type="javax.sql.DataSource"
maxActive="100" maxIdle="30" maxWait="10000"
username="vpb" password="vpb" driverClassName="net.sourceforge.jtds.jdbc.Driver"
url="jdbc:jtds:sqlserver://127.0.0.1:1433/VtolPaymentBridge;integrated security=false"/>


Âncora
_Toc434487107
_Toc434487107
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.

Âncora
_Toc434487108
_Toc434487108
3. Integración

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


Âncora
_Toc381043093
_Toc381043093
Âncora
_

...

Toc434487110
_

...

Toc434487110
3.2 Servicios brindados por VPB

VTOL Payment Bridge brinda los siguientes servicios:


Âncora
_

...

Toc381043094
_

...

Toc381043094
3.

...

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. 

...

VTOL Payment Bridge brinda los siguientes servicios:

...

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

...

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"

...

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.


Notar que la URL es sobre protocolo seguro HTTPS.


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


<html>

<body>

<form id="authorize"

name="authorize" action="https://10.4.14.56:8080/web-vtol/service/authorizeForm.html" method="post">

<input type="hidden" name="data"  id="data"

value="transactionId=transactionId|amount=110.99|promocionBanco=promo_all|orderDescription=El total de su compra es de $110.99. Ha elegido pagar en Pesos Argentinos (ARS)|aditionalData=|userID=juanc@sts.com|callbackErrorURL=http://localhost:8080/emulatorEcommerce/callbackErrorURL.jsp|callbackOKURL=http://localhost:8080/emulatorEcommerce/callbackOKURL.jsp|callBackCancel=http://localhost:8080/emulatorEcommerce/callBackCancel.jsp|payments=1|currency=$|[email protected]|cardId=NotDefined|plan=0|nombre=Andres|apellido=Bohinc|localidad=|domicilio=|provincia=|pais=|ipAdress=127.0.0.1)|message=Mensaje"/>

<form>

<script type="text/javascript">

document.authorize.submit();

</script>

</body>

</html>

...

el trace de transacciones. Es un valor incremental que inicia en 01 y su valor máximo es 99

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.

orderDescriptionAlfanuméricoOpcionalEste campo se utiliza para enviar desde el eCommerce una leyenda que se mostrará en el formulario de VPB. En caso de que no se envíe este campo, se mostrará una leyenda por defecto.

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.
Importante: que haya sido enviado a VTOL Server no significa que la operación este Aprobada.

callbackCancelAlfanuméricoObligatorioURL de respuesta que será invocado cuando el pago de la compra sea cancelado por el usuario desde VPB.

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
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>

...

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

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
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:
transactionId=697900|status=Commit


Âncora
_Códigos_de_respuesta
_Códigos_de_respuesta
Âncora
_Toc434487112
_Toc434487112
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

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

...