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. |
20/08/2019 | 1.4 | Agregado de los campos Company y Store en la invocación de los servicios brindados por VPB. |
Í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 eCommerce 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
Además, el formulario de VTOL Payment Bridge permitirá ingresar datos adicionales del titular de la tarjeta, como ser Fecha de nacimiento, Tipo y Número de Documento, y Dirección. Estos datos podrán ser enviados por el eCommerce a VPB en el mensaje de autorización de pago, o que VPB se los solicite al usuario en el formulario de ingreso de datos. Se mostrará una imagen como la siguiente:
Formulario de VPB con datos adicionales del tarjeta habiente
1.3 Ventajas
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 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
- 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.
1.5.2 E-Commerce
- 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.
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.
- Instalar y configurar el servidor Tomcat 9 como servicio. Link: tomcat.apache.org/download-90.cgi
- Descargar JDK 1.8+
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
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.8.X de 64bits |
Contenedor Web | Tomcat versión 9 |
Base de datos | MSSQL 2008 o superior |
2.3 Instalación
- Correr desde la consola el instalador con el comando:
cmd: java -jar vtol-payment-bridge-installer-3.8.0.3-SNAPSHOT.jar
- Aceptar la licencia
- Ingresar la ruta de la JDK
- Ingresar la ruta donde está instalado Tomcat 9
- Seleccionar si desea realizar la instalación completa.
Solo para Instalación completa
Ingresar la ruta del certificado de seguridad
Ingresar el password del certificado de seguridad
- Ingresar las credenciales de conexión a la base de datos SQL SERVER.
Para instalación completa y parcial
- Se desplegará la siguiente imagen:
- La finalización de la instalación se informa mediante un mensaje de "Terminado". Oprimir "Aceptar".
- Presionar el botón "Salir" para salir del instalador.
- Dentro del directorio NNNN se creó la carpeta con la nueva versión instalada de VTOL Payment Bridge.
- A continuación, lo que se debe realizar es ejecutar los scripts en la base de datos. Ver el apartado 2.5 Creación de base de datos
Importante
Sólo se podrá crear una base de datos 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 ruta \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 Transacción en 1 fase (Venta)
VTOL Payment Bridge ofrece la posibilidad de realizar una transacción en una sola fase, llamada Venta (cargo). Directamente se realiza la transacción financiera. En esta modalidad VPB autoriza, verifica y captura todo de una vez.
3.2.1.1 Solicitud de Pago
Servicio: /authorizeForm
Para realizar una solicitud de Pago, se debe invocar un método POST al endpoint de VPB, enviando el atributo transactionType=sale.
Los campos se envían en formato json "Nombre del campo":"valor"
Invocación:
En la invocación POST se envían los siguientes parámetros con los datos de la venta
:
Parámetro | Tipo | Obligatorio | Descripción | ||
---|---|---|---|---|---|
ecommerce | Object | SI | Datos del comercio electrónico | ||
company | Numérico | SI | Código de la compañía que realiza la solicitud de pago. | ||
store | Numérico | SI | Código de la tienda asociada a la compañía que realiza la solicitud de pago. | ||
transactionType | Alfanumérico | SI | Tipo de transacción. Enviar sale | ||
transactionId | Numérico | SI | 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. | ||
autoCommit | Boolean | NO | Identifica si las transacciones serán confirmadas por VPB sin esperar un "tercer mensaje". Valores posibles: True: Las transacciones que retornen aprobadas desde VTOL, serán confirmadas automáticamente. False: Las transacciones que retornen aprobadas desde VTOL, deberán ser confirmadas con un tercer mensaje por parte del eCommerce. Si no se envía este campo, por defecto se toma el valor False. | ||
paymentData | Object | ||||
plan | Alfanumérico | SI | Plan. Enviar valor 0. | ||
payments | Numérico | SI | Cantidad de cuotas. | ||
paymentCondition | Alfanumérico | NO | Condición de pago, asociada con el campo payments. Sólo se encuentra presente si existe una condición de pago vinculada con la transacción. | ||
additionalCardHolder | Boolean | NO | Campo que podrá enviar el eCommerce para que VPB solicite datos adicionales del tarjeta habiente en el formulario de pago, para ser validados por antifraude. Estos datos serán enviados en el objeto cardHolder. Valores posibles: True: VPB solicitará los datos adicionales del tarjeta habiente en el formulario de pago. False: VPB no solicitará datos adicionales del tarjeta habiente en el formulario. Dichos datos deberán ser enviados por el eCommerce. Si no se envía este campo, los datos adicionales del cliente no serán solicitados por ningún sistema. | ||
cardHolder | Object | NO | Datos del titular de la tarjeta. | ||
prefixCardNumber | Numérico | NO | 6 primeros dígitos de la tarjeta. | ||
identificationType | Alfanumérico | Condicional | Tipo de identificación. Valores posibles: 0: CUIT Obligatorio si additionalCardHolder= | ||
identificationNumber | Numérico | Condicional | Número de identificación. Máximo 8 dígitos. Obligatorio si additionalCardHolder= | ||
birthdate | Date | Condicional | Fecha de nacimiento del tarjeta habiente. Formato YYYYMMDD. Obligatorio si additionalCardHolder= | ||
phone | Numérico | NO | Teléfono del tarjeta habiente. Máximo 11 dígitos. | ||
deliveryAddress | Object | NO | Datos de dirección de entrega del resumen de la tarjeta del pagador. | ||
streetName | Alfanumérico | Condicional | Calle. Obligatorio si additionalCardHolder= | ||
streetNumber | Numérico | Condicional | Número de puerta. Obligatorio si additionalCardHolder= | ||
complement | Alfanumérico | NO | Piso / departamento. | ||
zipCode | Numérico | NO | Código postal. Máximo 4 dígitos. | ||
customerData | Object | NO | Datos del usuario registrado en el e-commerce | ||
customerName | Alfanumérico | NO | Nombre del cliente del e-commerce | ||
customerLastName | Alfanumérico | NO | Apellido del cliente del e-commerce | ||
customerIdentificationType | Alfanumérico | NO | Tipo de documento del cliente del e-commerce | ||
customerIdentificationNumber | Alfanumérico | NO | Número de documento del cliente del e-commerce | ||
customerId | Alfanumérico | NO | Nombre o id del usuario del e-commerce. | ||
customerIP | Alfanumérico | SI | Dirección IP del usuario del e-commerce. | ||
cardValidation | Object | NO | Datos que utilizará VPB para validar la tarjeta ingresada por el usuario web en el formulario. | ||
brand | Alfanumérico | NO | Marca de la tarjeta. Máximo 10 caracteres. | ||
provider | Alfanumérico | NO | Código del Provider de tarjeta. Ejemplo VI (Visa). Longitud máxima 20. | ||
bank | Alfanumérico | NO | Banco emisor de la tarjeta. Longitud máxima 20. | ||
amount | Numérico | SI | Importe total a pagar. | ||
currency | Alfanumérico | SI | Tipo de Moneda:
| ||
interestAmount | Alfanumérico | NO | Este campo es por si se necesita enviar el monto de los intereses en el mensaje a Autorizar. Normalmente el monto ya contiene los intereses en el caso de pagar en cuotas. Pero existen casos de tarjetas especiales donde el monto hay que enviarlo libre de intereses y en otro campo los intereses. | ||
url | Object | SI | Datos de las URLs de callback. | ||
callbackUrlError | Alfanumérico | SI | URL de respuesta a la cual VPB hace la redirección 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. | ||
callbackUrlSuccessful | Alfanumérico | SI | URL de respuesta a la cual VPB hace la redirección cuando el requerimiento finaliza correctamente. En la invocación se envía el transacciónID correspondiente. | ||
callbackUrlCancel | Alfanumérico | SI | URL de respuesta que será invocado cuando el pago de la compra sea cancelado por el usuario desde VPB. | ||
checkTransactionStatus | Alfanumérico | SI | URL definida por el e-commerce donde VPB podrá realizar una invocación GET, y poder obtener qué acción realizar sobre una transacción, confirmarla o cancelarla. Ver Servicios brindados por el ecommerce | ||
formData | Object | NO | Datos del comercio que se mostrarán en el formulario de ingreso de datos de la tarjeta | ||
merchantName | Alfanumérico | NO | Nombre que se visualizará en el formulario para el ingreso de datos de la tarjeta. Si no se envía este campo, se mostrará un nombre por defecto. | ||
merchantImageURL | Alfanumérico | NO | URL donde VPB podrá tomar la imagen que se visualizará en el formulario para el ingreso de datos de la tarjeta. Si no se envía este campo, se mostrará una imagen por defecto. | ||
merchantImageMobileURL | Alfanumérico | NO | URL donde VPB podrá tomar la imagen que se visualizará en el formulario para el ingreso de datos de la tarjeta en dispositivos móviles y tablets. Si no se envía este campo, se mostrará una imagen por defecto. | ||
orderDescription | Alfanumérico | NO | Este 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. | ||
posTicket | Alfanumérico | NO | Información del ticket en formato xml y posteriormente transformado en Base 64. Ver sección Estructura del campo posTicket | ||
ecommerceCustomField | Alfanumérico | NO | Máximo 255 caracteres. Campo generado por el eCommerce, lo puede enviar a VPB para que este lo guarde y pueda ser usado para trazabilidad del eCommerce. | ||
formTimeout | Alfanumérico | NO | Tiempo de espera para cargar los datos de la tarjeta en el formulario de VPB. |
* Campos Condicionales:
Si additionalPayerData=False
, entonces el eCommerce debe enviar obligatoriamente los siguientes campos:
- identificationType
- identificationNumber
- birthdate
- streetName
- streetNumber
Si additionalPayerData=True
, entonces VPB deberá solicitar obligatoriamente los siguientes campos en el formulario:
- identificationType
- identificationNumber
- birthdate
- streetName
- streetNumber
Ejemplo:
{ "ecommerce": { "company": "1", "store": "1" }, "transactionType": "sale", "autoCommit": false, "additionalCardHolder": false, "transactionId": 1569441914224, "orderDescription": "El total de su compra es de $110.99. Ha elegido pagar en Pesos Argentinos (ARS)", "amount": "110.90", "currency": "$", "interestAmount": "0", "userId": "", "posTicket": "", "ecommerceCustomField": "", "cardHolder": { "identificationType": "1", "identificationNumber": "32058821", "birthdate": "22/07/1986", "phone": "3425340300", "deliveryAddress": { "streetName": "25 de mayo", "streetNumber": "3587", "complement": "2B", "zipCode": "3000" } }, "url": { "callbackUrlError": "https://localhost:8843/emulatorEcommerce/callbackErrorURL.jsp", "callbackUrlSuccessful": "https://localhost:8843/emulatorEcommerce/callbackOKURL.jsp", "callbackUrlCancel": "https://localhost:8843/emulatorEcommerce/callBackCancel.jsp", "checkTransactionStatus": "http://localhost:8280/emulatorEcommerce/service/checkStatusReturnRandom.html" }, "formData": { "merchantName": "My Company", "merchantImageURL": "https://ip/image.png" }, "paymentData": { "payments": "1", "plan": "0" }, "cardValidation": { "brand": "VISA", "provider": "VI", "bank": "BANCO GALICIA" }, "customerData": { "customerId": "100", "customerIP": "10.90.100.101", "customerName": "Juan Carlos", "customerLastName": "Rodriguez", "customerIdentificationType": "1", "customerIdentificationNumber": "32123456" } }
Respuesta:
La respuesta se realiza en el dirección de callback, especificada por el eCommerce. Los campos se envían en formato json "Nombre del campo":"valor".
Se responden los siguientes campos:
Parámetro | Tipo | Descripción |
---|---|---|
transactionId | Numérico | Identificador de la transacción de pago generado por el eCommerce. |
company | Numérico | Código de la compañía que realiza la compra. |
store | Numérico | Código de la tienda asociada a la compañía que realiza la compra. |
transactionType | Alfanumérico | Tipo de transacción realizada. |
Importante
Cuando el eCommerce recibe la notificación, tiene que obtener la información completa del recurso notificado, accediendo al endpoint correspondiente de la API: /checkTransactionStatus
Ejemplo de respuesta:
{ "transactionId":"1567105313489", "company":"55", "store":"1", "transactionType":"sale" }
3.2.1.2 Consultar Estado de Transacción
Servicio: /checkTransactionStatus
VPB permite consultar el estado y los datos de una operación, a través de una invocación GET a la URL de VPB.
Invocación:
En la invocación GET se envían los siguientes parámetros de la operación:
Campo | Tipo | Obligatorio | Descripción |
---|---|---|---|
transactionId | Numérico | SI | Identificador de la transacción de pago generado por el ecommerce. |
company | Numérico | SI | Código de la compañía que realiza la consulta. |
store | Numérico | SI | Código de la tienda asociada a la compañía que realiza la consulta. |
Los campos se envían en formato json "Nombre del campo":"valor"
Ejemplo:
{ "transactionId":"1567105313489", "company":"1", "store":"1" }
Respuesta:
La respuesta retorna los siguientes campos:
Campo | Tipo | Descripción |
---|---|---|
responseCode | Numérico | Código de Respuesta de la transacción. Ver sección Códigos de Respuesta. |
responseMessage | 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. Longitud entre 19 y 20 dígitos, debido a que utiliza el día como parte de formato. |
providerCode | Alfanumérico | Código de autorizador. Ejemplo: Banamex |
displayMessage | Alfanumérico | Mensaje adicional enviado por el autorizador y que debe ser visualizado. |
Los campos se responden en formato json "Nombre del campo":"valor"
Ejemplo de respuesta:
{ "amount":"110.99", "providerCode":"Visa", "ticket":"27", "authorizationCode":"123456", "store":1, "transactionDate":"2019-08-29 16:02:13.743", "responseCode":"000", "node":"0000000005", "displayMessage":"esta es una prueba de impresion", "currency":"$", "company":1, "id":1350, "responseMessage":"APROBADA", "vtolTrxId":"29081916021600000277", "status":"Commit" }
3.2.1.3 Cierre de Transacción
Servicio: /closeTransaction
VPB permite cerrar la transacción para confirmarla o cancelarla, a través de un método POST a la URL de VPB.
Invocación:
En la invocación POST se envían los siguientes parámetros de la operación:
Campo | Tipo | Obligatorio | Descripción |
---|---|---|---|
company | Numérico | SI | Código de la compañía que realiza el cierre de la transacción. |
store | Numérico | SI | Código de la tienda asociada a la compañía que realiza el cierre de la transacción. |
transactionId | Numérico | SI | Identificador de la transacción de pago generado por el ecommerce. |
action | Alfanumérico | SI | commit: Confirmada rollback: Cancelada |
Los campos se envían en formato json "Nombre del campo":"valor"
Ejemplo:
{ "company":"1", "store":"1", "transactionType":"sale", "transactionId":"1567105313489", "action":"commit" }
Respuesta:
La respuesta sólo retorna un código HTTP 200.
Importante
Luego de recibir el código HTTP 200, el eCommerce deberá consultar el estado de la transacción, para confirmar que el Cierre de Transacción se realizó correctamente. Para eso deberá invocar el servicio /checkTransactionStatus con un método GET.
3.2.2 Transacción en 2 fases (Autorización y Captura)
VTOL Payment Bridge ofrece la posibilidad de realizar transacciones en dos pasos, primero se realiza una autorización, y luego se genera la captura. Son operaciones llamadas de dos fases.
La autorización es una reserva de fondos en la tarjeta del comprador. Esto significa que al realizar la misma, todavía no se generó un cobro al cliente en su tarjeta. Nunca aparece en el resumen de cuenta del tarjeta habiente. Solo cuando se realice una captura el cliente verá el pago.
3.2.2.1 Autorización de Pago
Servicio: /authorizeForm
El pedido de autorización es un servicio que valida la información de la tarjeta que se envía, para verificar si se puede continuar con el proceso de pago y reservar los fondos del tarjeta habiente.
Para realizar una autorización, se debe invocar un método POST a la URL de VPB, enviando el atributo transactionType=authorization.
Los campos se envían en formato json "Nombre del campo":"valor"
Invocación:
En la invocación POST se envían los siguientes parámetros con los datos de la autorización
:
Parámetro | Tipo | Obligatorio | Descripción | ||
---|---|---|---|---|---|
ecommerce | Object | SI | Datos del comercio electrónico | ||
company | Numérico | SI | Código de la compañía que realiza la solicitud de pago. | ||
store | Numérico | SI | Código de la tienda asociada a la compañía que realiza la solicitud de pago. | ||
transactionType | Alfanumérico | SI | Tipo de transacción. Enviar authorization | ||
transactionId | Numérico | SI | 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. | ||
autoCommit | Boolean | NO | Identifica si las transacciones serán confirmadas por VPB sin esperar un "tercer mensaje". Valores posibles: True: Las transacciones que retornen aprobadas desde VTOL, serán confirmadas automáticamente. False: Las transacciones que retornen aprobadas desde VTOL, deberán ser confirmadas con un tercer mensaje por parte del eCommerce. Si no se envía este campo, por defecto se toma el valor False. | ||
paymentData | Object | ||||
plan | Alfanumérico | SI | Plan. Enviar valor 0. | ||
payments | Numérico | SI | Cantidad de cuotas. | ||
paymentCondition | Alfanumérico | NO | Condición de pago, asociada con el campo payments. Sólo se encuentra presente si existe una condición de pago vinculada con la transacción. | ||
additionalCardHolder | Boolean | NO | Campo que podrá enviar el eCommerce para que VPB solicite datos adicionales del tarjeta habiente en el formulario de pago, para ser validados por antifraude. Estos datos serán enviados en el objeto cardHolder. Valores posibles: True: VPB solicitará los datos adicionales del tarjeta habiente en el formulario de pago. False: VPB no solicitará datos adicionales del tarjeta habiente en el formulario. Dichos datos deberán ser enviados por el eCommerce. Si no se envía este campo, los datos adicionales del cliente no serán solicitados por ningún sistema. | ||
cardHolder | Object | NO | Datos del titular de la tarjeta. | ||
prefixCardNumber | Numérico | NO | 6 primeros dígitos de la tarjeta. | ||
identificationType | Alfanumérico | Condicional | Tipo de identificación. Valores posibles: 0: CUIT Obligatorio si additionalCardHolder= | ||
identificationNumber | Numérico | Condicional | Número de identificación. Máximo 8 dígitos. Obligatorio si additionalCardHolder= | ||
birthdate | Date | Condicional | Fecha de nacimiento del tarjeta habiente. Formato YYYYMMDD. Obligatorio si additionalCardHolder= | ||
phone | Numérico | NO | Teléfono del tarjeta habiente. Máximo 11 dígitos. | ||
deliveryAddress | Object | NO | Datos de dirección de entrega del resumen de la tarjeta del pagador. | ||
streetName | Alfanumérico | Condicional | Calle. Obligatorio si additionalCardHolder= | ||
streetNumber | Numérico | Condicional | Número de puerta. Obligatorio si additionalCardHolder= | ||
complement | Alfanumérico | NO | Piso / departamento. | ||
zipCode | Numérico | NO | Código postal. Máximo 4 dígitos. | ||
customerData | Object | NO | Datos del usuario registrado en el e-commerce | ||
customerName | Alfanumérico | NO | Nombre del cliente del e-commerce | ||
customerLastName | Alfanumérico | NO | Apellido del cliente del e-commerce | ||
customerIdentificationType | Alfanumérico | NO | Tipo de documento del cliente del e-commerce | ||
customerIdentificationNumber | Alfanumérico | NO | Número de documento del cliente del e-commerce | ||
customerId | Alfanumérico | NO | Nombre o id del usuario del e-commerce. | ||
customerIP | Alfanumérico | SI | Dirección IP del usuario del e-commerce. | ||
cardValidation | Object | NO | Datos que utilizará VPB para validar la tarjeta ingresada por el usuario web en el formulario. | ||
brand | Alfanumérico | NO | Marca de la tarjeta. Máximo 10 caracteres. | ||
provider | Alfanumérico | NO | Código del Provider de tarjeta. Ejemplo VI (Visa). Longitud máxima 20. | ||
bank | Alfanumérico | NO | Banco emisor de la tarjeta. Longitud máxima 20. | ||
amount | Numérico | SI | Importe total a pagar. | ||
currency | Alfanumérico | SI | Tipo de Moneda:
| ||
interestAmount | Alfanumérico | NO | Este campo es por si se necesita enviar el monto de los intereses en el mensaje a Autorizar. Normalmente el monto ya contiene los intereses en el caso de pagar en cuotas. Pero existen casos de tarjetas especiales donde el monto hay que enviarlo libre de intereses y en otro campo los intereses. | ||
url | Object | SI | Datos de las URLs de callback. | ||
callbackUrlError | Alfanumérico | SI | URL de respuesta a la cual VPB hace la redirección 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. | ||
callbackUrlSuccessful | Alfanumérico | SI | URL de respuesta a la cual VPB hace la redirección cuando el requerimiento finaliza correctamente. En la invocación se envía el transacciónID correspondiente. | ||
callbackUrlCancel | Alfanumérico | SI | URL de respuesta que será invocado cuando el pago de la compra sea cancelado por el usuario desde VPB. | ||
checkTransactionStatus | Alfanumérico | SI | URL definida por el e-commerce donde VPB podrá realizar una invocación GET, y poder obtener qué acción realizar sobre una transacción, confirmarla o cancelarla. Ver Servicios brindados por el ecommerce | ||
formData | Object | NO | Datos del comercio que se mostrarán en el formulario de ingreso de datos de la tarjeta | ||
merchantName | Alfanumérico | NO | Nombre que se visualizará en el formulario para el ingreso de datos de la tarjeta. Si no se envía este campo, se mostrará un nombre por defecto. | ||
merchantImageURL | Alfanumérico | NO | URL donde VPB podrá tomar la imagen que se visualizará en el formulario para el ingreso de datos de la tarjeta. Si no se envía este campo, se mostrará una imagen por defecto. | ||
merchantImageMobileURL | Alfanumérico | NO | URL donde VPB podrá tomar la imagen que se visualizará en el formulario para el ingreso de datos de la tarjeta en dispositivos móviles y tablets. Si no se envía este campo, se mostrará una imagen por defecto. | ||
orderDescription | Alfanumérico | NO | Este 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. | ||
posTicket | Alfanumérico | NO | Información del ticket en formato xml y posteriormente transformado en Base 64. Ver sección Estructura del campo posTicket | ||
ecommerceCustomField | Alfanumérico | NO | Máximo 255 caracteres. Campo generado por el eCommerce, lo puede enviar a VPB para que este lo guarde y pueda ser usado para trazabilidad del eCommerce. | ||
formTimeout | Alfanumérico | NO | Tiempo de espera para cargar los datos de la tarjeta en el formulario de VPB. |
* Campos Condicionales:
Si additionalPayerData=False
, entonces el eCommerce debe enviar obligatoriamente los siguientes campos:
- identificationType
- identificationNumber
- birthdate
- streetName
- streetNumber
Si additionalPayerData=True
, entonces VPB deberá solicitar obligatoriamente los siguientes campos en el formulario:
- identificationType
- identificationNumber
- birthdate
- streetName
- streetNumber
Ejemplo:
{ "ecommerce": { "company": "1", "store": "1" }, "transactionType": "authorization", "autoCommit": false, "additionalCardHolder": false, "transactionId": 1569441914255, "orderDescription": "El total de su compra es de $110.99. Ha elegido pagar en Pesos Argentinos (ARS)", "amount": "110.90", "currency": "$", "interestAmount": "0", "userId": "", "posTicket": "", "ecommerceCustomField": "", "cardHolder": { "identificationType": "1", "identificationNumber": "32058821", "birthdate": "22/07/1986", "phone": "3425340300", "deliveryAddress": { "streetName": "25 de mayo", "streetNumber": "3587", "complement": "2B", "zipCode": "3000" } }, "url": { "callbackUrlError": "https://localhost:8843/emulatorEcommerce/callbackErrorURL.jsp", "callbackUrlSuccessful": "https://localhost:8843/emulatorEcommerce/callbackOKURL.jsp", "callbackUrlCancel": "https://localhost:8843/emulatorEcommerce/callBackCancel.jsp", "checkTransactionStatus": "http://localhost:8280/emulatorEcommerce/service/checkStatusReturnRandom.html" }, "formData": { "merchantName": "My Company Name", "merchantImageURL": "https://IP/companyImage.png" }, "paymentData": { "payments": "1", "plan": "0" }, "cardValidation": { "brand": "VISA", "provider": "VI", "bank": "BANCO GALICIA" }, "customerData": { "customerId": "100", "customerIP": "10.90.100.101", "customerName": "Juan Carlos", "customerLastName": "Messi", "customerIdentificationType": "1", "customerIdentificationNumber": "32123456" } }
Respuesta:
La respuesta se realiza en la dirección de callback, especificada en el POST inicial. De esta manera se devuelve el control al eCommerce.
Retorna los siguientes campos:
Parámetro | Tipo | Descripción |
---|---|---|
company | Numérico | Código de la compañía que realiza la compra. |
store | Numérico | Código de la tienda asociada a la compañía que realiza la compra. |
transactionId | Numérico | Identificador de la transacción de pago generado por el eCommerce. |
transactionType | Alfanumérico | Tipo de transacción. |
Los campos se envían en formato json "Nombre del campo":"valor"
Ejemplo de respuesta:
{ "transactionId":"1567105313489", "company":"55", "store":"1", "transactionType":"authorization" }
Tener en cuenta
La reserva tendrá una validez de 15 días. Si no se realiza la captura hasta ese momento, será cancelada automáticamente.
La reserva también puede resultar rechazada, al igual que ocurre con una operación convencional, dependiendo si pasa las validaciones de la tarjeta.
Los fondos reservados no podrán ser utilizados por el comprador hasta que no sean capturados, por lo cual se recomienda realizar la captura en el menor tiempo posible.
3.2.2.2 Consultar Estado de Transacción
Servicio: /checkTransactionStatus
VPB permite consultar el estado y los datos de una autorización, a través de una invocación GET a la URL de VPB.
La invocación a este servicio es el mismo que en las operaciones de una fase: Consultar Estado de Transacción
3.2.2.3 Captura de Pago
Servicio: /closeTransaction
Esta operatoria se utiliza exclusivamente luego de haber realizado un Pedido de Autorización en 2 pasos.
Para poder confirmar definitivamente el pago al cliente, es necesario capturar los fondos que se reservaron. Es posible realizar la captura por el monto total o de forma parcial.
Capturar el monto total de una reserva
Para hacer la captura por el monto total, se realizará una invocación POST a la URL de VPB, sin informar el monto, y enviando el atributo action=commit.
Los campos se envían en formato json "Nombre del campo":"valor"
Invocación:
En la invocación POST se envían los siguientes parámetros con los datos de la captura
:
Parámetro | Tipo de dato | Obligatorio | Descripción |
---|---|---|---|
company | Numérico | SI | Código de la compañía que realiza la solicitud de pago. |
store | Numérico | SI | Código de la tienda asociada a la compañía que realiza la solicitud de pago. |
transactionId | Numérico | SI | Identificador de la transacción de pago generado por el eCommerce. |
action | Alfanumérico | SI | Valores posibles: commit: Confirmada |
Ejemplo:
{ "company":"1", "store":"1", "transactionId":"1567105313489", "action":"commit" }
Respuesta:
La respuesta sólo retorna un código HTTP 200.
Importante
Luego de recibir el código HTTP 200, el eCommerce deberá consultar el estado de la transacción, para confirmar que la Captura se realizó correctamente. Para eso deberá invocar el servicio /checkTransactionStatus con un método GET.
Capturar un monto distinto al reservado
Para hacer la captura por un monto distinto (mayor o menor) al reservado, se realizará una invocación POST a la URL de VPB, informando el monto con el importe definitivo, y enviando el atributo action=commit.
Los campos se envían en formato json "Nombre del campo":"valor"
Invocación:
En la invocación POST se envían los siguientes parámetros con los datos de la captura
:
Parámetro | Tipo de dato | Obligatorio | Descripción |
---|---|---|---|
company | Numérico | SI | Código de la compañía que realiza la solicitud de pago. |
store | Numérico | SI | Código de la tienda asociada a la compañía que realiza la solicitud de pago. |
transactionId | Numérico | SI | Identificador de la transacción de pago generado por el eCommerce. |
amount | Numérico | SI | Importe definitivo de la venta. |
action | Alfanumérico | SI | Valores posibles: commit: Confirmada |
Ejemplo:
{ "company":"1", "store":"1", "transactionId":"1567105313489", "amount":500.22, "action":"commit" }
Respuesta:
La respuesta sólo retorna un código HTTP 200.
Importante
Luego de recibir el código HTTP 200, el eCommerce deberá consultar el estado de la transacción, para confirmar que la Captura se realizó correctamente. Para eso deberá invocar el servicio /checkTransactionStatus con un método GET.
3.2.2.4 Cancelar una Autorización de Pago
Servicio: /closeTransaction
Para realizar la cancelación de una autorización, se debe invocar un método POST a la URL de VPB, enviando el atributo action=rollback.
Los campos se envían en formato json "Nombre del campo":"valor"
Invocación:
En la invocación POST se envían los siguientes parámetros con los datos de la cancelación
:
Parámetro | Tipo de dato | Obligatorio | Descripción |
---|---|---|---|
company | Numérico | SI | Código de la compañía que realiza la solicitud de pago. |
store | Numérico | SI | Código de la tienda asociada a la compañía que realiza la solicitud de pago. |
transactionId | Numérico | SI | Identificador de la transacción de pago generado por el eCommerce. |
action | Alfanumérico | SI | Enviar rollback: Cancelar autorización |
Ejemplo:
{ "company":"1", "store":"1", "transactionId":"1567105313489", "action":"rollback" }
Respuesta:
La respuesta sólo retorna un código HTTP 200.
Importante
Luego de recibir el código HTTP 200, el eCommerce deberá consultar el estado de la transacción, para confirmar que la Cancelación de la Autorización se realizó correctamente. Para eso deberá invocar el servicio /checkTransactionStatus con un método GET.
3.2.4 Devoluciones
VTOL Payment Bridge ofrece la posibilidad de realizar devoluciones de un pago. La operación original debe ser menor a 30 días.
La Devolución de una Transacción de dos pasos, se hace por el monto efectivamente capturado (en el 2do paso).
A través de este método se realizan devoluciones totales o parciales. Para ello la transacción debe estar en estado Acreditada.
3.2.4.1 Realizar devolución total del pago
Servicio: /refunds
Se debe invocar un método POST a la URL de VPB, sin informar el monto, y enviando el atributo transactionType=refund.
Si no se informa el monto, la devolución se hará por el total de la orden.
Invocación:
Parámetro | Tipo de dato | Obligatorio | Descripción | |
---|---|---|---|---|
ecommerce | Object | SI | Datos del comercio electrónico | |
company | Numérico | SI | Código de la compañía que realiza la solicitud de pago. | |
store | Numérico | SI | Código de la tienda asociada a la compañía que realiza la solicitud de pago. | |
transactionType | Alfanumérico | SI | Tipo de transacción. Enviar refund | |
originalTrxId | Numérico | SI | Identificador de la transacción de compra original. Es el transactionId que se envió en la operación de compra. | |
transactionId | Numérico | SI | Identificador de la transacción de devolución. 16 dígitos de longitud. Debe ser generado por el e-commerce de manera tal que identifique unívocamente a una operación, 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. | |
amount | Numérico | NO | Importe de la devolución. La separación de decimales se realiza con un punto. Ejemplo: (200.00). Puede ser menor o igual al monto original de la compra. Si no se envía, entonces la devolución será por el total de la compra. | |
currency | Alfanumérico | NO | Tipo de Moneda: $ = Pesos U$S = Dólares | |
url | Object | SI | Datos de las URLs de callback. | |
callbackUrlError | Alfanumérico | SI | URL de respuesta a la cual VPB hace la redirección 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. | |
callbackUrlSuccessful | Alfanumérico | SI | URL de respuesta a la cual VPB hace la redirección cuando el requerimiento finaliza correctamente. En la invocación se envía el transacciónID correspondiente. | |
getTransactionStatus | Alfanumérico | SI | URL definida por el e-commerce donde VPB podrá realizar una invocación GET, y poder obtener qué acción realizar sobre una transacción, confirmarla o cancelarla. Ver Servicios brindados por el ecommerce |
3.2.4.2 Realizar devolución parcial del pago
Servicio: /refunds
Se debe invocar un método POST a la URL de VPB, enviando el atributo transactionType=refund.
Es posible realizar devoluciones parciales (incluso más de una por orden, siempre y cuando no se supere el monto de la misma).
Se debe indicar el monto a devolver, en el campo amount
.
Parámetro | Tipo de dato | Obligatorio | Descripción | |
---|---|---|---|---|
ecommerce | Object | SI | Datos del comercio electrónico | |
company | Numérico | SI | Código de la compañía que realiza la solicitud de pago. | |
store | Numérico | SI | Código de la tienda asociada a la compañía que realiza la solicitud de pago. | |
transactionType | Alfanumérico | SI | Tipo de transacción. Enviar refund | |
originalTrxId | Numérico | SI | Identificador de la transacción de compra original. Es el transactionId que se envió en la operación de compra. | |
transactionId | Numérico | SI | Identificador de la transacción de devolución. 16 dígitos de longitud. Debe ser generado por el e-commerce de manera tal que identifique unívocamente a una operación, 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. | |
amount | Numérico | SI | Importe de la devolución. La separación de decimales se realiza con un punto. Ejemplo: (200.00). Puede ser menor o igual al monto original de la compra. | |
currency | Alfanumérico | SI | Tipo de Moneda: $ = Pesos U$S = Dólares | |
url | Object | SI | Datos de las URLs de callback. | |
callbackUrlError | Alfanumérico | SI | URL de respuesta a la cual VPB hace la redirección 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. | |
callbackUrlSuccessful | Alfanumérico | SI | URL de respuesta a la cual VPB hace la redirección cuando el requerimiento finaliza correctamente. En la invocación se envía el transacciónID correspondiente. | |
getTransactionStatus | Alfanumérico | SI | URL definida por el e-commerce donde VPB podrá realizar una invocación GET, y poder obtener qué acción realizar sobre una transacción, confirmarla o cancelarla. Ver Servicios brindados por el ecommerce |
Respuesta:
La respuesta se realiza en la dirección de callback, especificada por el eCommerce en la operación de devolución.
Se responden los siguientes campos:
Parámetro | Tipo | Descripción |
---|---|---|
company | Numérico | Código de la compañía que realiza la compra. |
store | Numérico | Código de la tienda asociada a la compañía que realiza la compra. |
transactionId | Numérico | Identificador de la transacción de devolución generado por el eCommerce. |
transactionType | Alfanumérico | Tipo de transacción: refund |
Importante
Cuando el eCommerce recibe la notificación, tiene que obtener la información completa del recurso notificado, accediendo al endpoint correspondiente de la API: /checkTransactionStatus
3.2.4.3 Cierre de transacción
Servicio: /closeTransaction
VPB permite cerrar la transacción de Devolución para confirmarla o cancelarla, a través de un método POST a la URL de VPB. Esta operación se debe llevar a cabo para poder cerrar la transacción.
Invocación:
En la invocación POST se envían los siguientes parámetros de la operación:
Campo | Tipo | Obligatorio | Descripción |
---|---|---|---|
company | Numérico | SI | Código de la compañía que realiza el cierre de la transacción. |
store | Numérico | SI | Código de la tienda asociada a la compañía que realiza el cierre de la transacción. |
transactionId | Numérico | SI | Identificador de la transacción de pago generado por el ecommerce. |
action | Alfanumérico | SI | commit: Confirmada rollback: Cancelada |
Los campos se envían en formato json "Nombre del campo":"valor"
Ejemplo:
{ "transactionId": "11445878985", "ecommerce": { "company": "1", "store": "1" }, "action": "commit" }
Respuesta:
La respuesta sólo retorna un código HTTP 200.
Importante
Luego de recibir el código HTTP 200, el eCommerce deberá consultar el estado de la transacción, para confirmar que la operación de Devolución se realizó correctamente. Para eso deberá invocar el servicio /checkTransactionStatus con un método GET.
3.3 Servicios 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 Consultar estado de transacción
VPB debe poder realizar una invocación GET a un servicio que disponibiliza el e-commerce. VPB debe conocer la URL del servicio para poder realizar la consulta. Dicha URL será informada por el e-commerce en el mensaje de Solicitud de Pago.
Servicio: /getTransactionStatus
Invocación:
En la invocación GET se envían los siguientes parámetros de la operación dentro de la URL:
Parámetro | Tipo | Obligatorio | Descripción |
---|---|---|---|
company | Numérico | SI | Código de la compañía que realiza la solicitud de pago. |
store | Numérico | SI | Código de la tienda asociada a la compañía que realiza la solicitud de pago. |
transactionId | Numérico | SI | Identificador de la transacción de pago generado por el ecommerce. |
Ejemplo:
https://www.e-commerce.com/service/getTransactionStatus.html?transactionId=1567105313489&company=1&store=1
Respuesta:
La respuesta retornará los siguientes campos:
Parámetro | Tipo | Descripción |
---|---|---|
company | Numérico | Código de la compañía que realiza la solicitud de pago. |
store | Numérico | Código de la tienda asociada a la compañía que realiza la solicitud de pago. |
transactionId | Numérico | Identificador de la transacción. |
status | Alfanumérico | Estado de la transacción. Puede ser: Commit: Confirmada Rollback: Cancelada. |
Los campos se responden en formato json "Nombre del campo":"valor"
Ejemplo de respuesta:
200:{ "company":"1", "store":"1", "transactionId":"1567105313489", "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
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 |