VTOL Payment Bridge - Integración 3.8.0.5

1. Introducción

1.1 Acerca de este documento

Este documento describe los aspectos técnicos de integración, para aquellos comercios que deseen procesar cobros on-line, con sus sistemas de E-Commerce, a través de la API de VTOL Payment Bridge.

La implementación del servicio de VTOL Payment Bridge requiere conocimientos de desarrollo de software, para poder generar código que interactúe con la API de VPB para invocar servicios y procesar respuestas.

1.2 ¿Qué es VTOL Payment Bridge?

Es un componente Web que permite a un sitio de eCommerce capturar los datos de la tarjeta y del tarjeta habiente, para luego autorizar, a través de VTOL Server, los pagos de compras realizadas en Internet. De esta manera no es necesario que el comercio esté certificado bajo las normas PCI.

Cuando el cliente de la tienda online quiere pagar su compra con tarjeta, se hace una redirección segura hacia VTOL Payment Bridge, quien solicita los datos para efectuar el pago.

A continuación se muestra una imagen del formulario que solicita los datos de la 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, Dirección y Teléfono. Estos datos podrán ser enviados por el eCommerce a VPB en el mensaje de autorización de pago, o bien que VPB se los solicite al usuario en el formulario de ingreso de datos. Se mostrará una imagen como la siguiente:

Formulario de pago de VPB con datos adicionales del tarjeta habiente

1.3 Ventajas

Algunas de las ventajas de usar VTOL Payment Bridge son:

1. Velocidad de integración con VTOL Server.
2. Evitar implementar un formulario de ingreso de datos de tarjeta 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 Server.

1.4 Alcance

1.4.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.4.2 E-Commerce

1. Utilización de protocolo seguro https.
2. Consultar a VPB el estado y datos de la transacción autorizada.
3. Indicar a VPB si debe confirmar o cancelar la transacción.
4. 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.5 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.

1.6 Validaciones en el formulario VPB

El formulario que despliega VTOL Payment Bridge para el ingreso de datos de la tarjeta realiza una serie de validaciones sobre los datos que ingresa el usuario. En caso de que se ingresen mal los datos de la tarjeta, se mostrarán mensajes informando los errores para que el usuario los pueda corregir. Existen dos tipos de errores que se pueden cometer sobre los campos de ingreso:

• Omitir ingresar datos obligatorios.
• Ingresar datos de tarjeta inválidos.

Los errores del primer tipo, no son validados por VPB, directamente se validan en el browser. Por ejemplo, si no se ingresa el Titular de la tarjeta, se mostrará el siguiente mensaje: "El campo Nombre en Tarjeta es requerido".

Los errores del segundo tipo, sí son validados por VPB. Por ejemplo que se ingrese una tarjeta vencida, o un código de seguridad menor al largo requerido. Este tipo de error sólo permite que se intente hasta tres veces ingresar los datos. En el cuarto intento, VPB hará una redirección a la URL de CallbackError, informando el error al eCommerce. 

1.6.1 Time Out de la compra

En VPB se puede limitar el tiempo con el que el tarjetahabiente cuenta para completar los datos sensibles de la tarjeta. En el formulario de ingreso de datos se muestra un timer en la esquina superior derecha, con el tiempo corriendo hacia atrás.

Esta funcionalidad suele usarse en comercios que necesitan liberar entradas o butacas si la transacción lleva más de un determinado tiempo y no recibió respuesta de finalización de la transacción.

Por default, la sesión caduca en 5 minutos. Para cambiar este parámetro, se debe modificar un archivo de configuración.

1.7 Integración con VTOL Integration Services

Para que VPB pueda obtener las opciones de pago disponibles, deberá integrarse con VTOL Integration Services.

Se deberá configurar el siguiente valor de la propiedad "linkPago.visBaseUrl" del archivo "application.properties" ubicado en \apache-tomcat-9.0.11-windows-x64\conf

#URL del servicio VIS - Vtol Integration Service
linkPago.visBaseUrl=https://localhost:8554/v2/crdb/app/paymentLink

Las APIs de integración se encuentran especificadas en el siguiente documento: VTOL Integration Services - Integración.

2. Autenticación (HTTP Basic Authentication)

Para la integración con VPB a través de la API REST, se requiere autenticación HTTP Basic. El comercio necesitará las siguientes credenciales:

• Usuario
• Contraseña. 

Se deben enviar estos datos en el "Header" de cada invocación a los servicios de VPB.

• Las credenciales se utilizan en el backend del comercio y debe ser secreta. Las mismas serán provistas por el equipo de Soporte de NAPSE.

2.1 Servicios de VPB que requieren Basic Authentication

Los siguientes servicios utilizan autenticación HTTP Basic

• /service/v2/paymentIntention.html
• /service/v2/checkTransactionStatus.html
• /service/v2/closeTransaction.html
• /service/v2/refund.html

2.2 Flujo de una transacción con Basic Authentication

Diagrama de integración con HTTP Basic Authentication

1. El eCommerce desde su frontend solicita un token de acceso, por lo cual desde su backend el eCommerce invoca al servicio de VPB que permite crear una Intención de Pago al endpoint “/service/v2/paymentIntention” enviando todos los datos de la venta e incluyendo el usuario y la contraseña en el Header (Basic authentication). En el parámetro data pasa un JSON. Entre esos datos se envía el identificador de transacción generado por el eCommerce (transactionId), el cual es un valor único.
2. La respuesta del servicio “/paymentIntention” retorna un Token generado a partir del JSON recibido.
3. El backend del eCommerce envía el valor del Token generado en el paso 2 al frontend.
4. Desde el frontend del comercio se realiza un POST al formulario de VPB en el endpoint “/service/v2/authorizeForm” para cursar finalmente el Pago. El Token se informa como parámetro en la url del servicio.
5. VPB por su parte despliega una ventana segura para capturar los datos sensibles 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 /paymentIntention.
   
6. El eCommerce posteriormente realiza la consulta del estado de la transacción pasando como parámetro su identificador en una invocación GET a VPB. 
   
7. Por último y una vez que finalizó la operación con el cliente, el eCommerce realiza una invocación POST a VPB al endpoint "/service/v2/closeTransaction" 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.
   

2. Integración

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

2.1 Servicios brindados por VPB

Las operaciones disponibles son:

• Operaciones con tarjetas de crédito y débito
  • Transacción en 1 fase
    • Autorización de Pago
    • Autorización de Pago PEI
  • Transacción en 2 fases
    • Autorización de pago
    • Captura de pago (sólo para transacción en 2 pasos)
    • Cancelar autorización de pago (sólo para transacción en 2 pasos)
  • Consultar estado de transacción
  • Devoluciones
    • Devolución total de Pago y Pago PEI
    • Devolución parcial de Pago y Pago PEI
      
      

2.1.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 verifica y captura el importe de la venta, todo de una vez.

En este esquema también es posible realizar operaciones PEI (Pago Electrónico Inmediato). Dichos pagos se realizarán con tarjetas de débito, y las mismas serán autorizadas a través de Red LINK.

2.1.1.1 Intención de Pago

POST

Servicio: /web-vtol/service/v2/paymentIntention

La intención de pago es el primer paso necesario para ejecutar una transacción de pago entre un comercio y la API REST de VPB. Como resultado se obtiene un Token de acceso para poder cursar el pago.

Invocación:

En el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

En el POST enviar el atributo transactionType=sale.

* 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": "C1",
      "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": "Ref001",
   "cardHolder": {
      "identificationType": "2",
      "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": "2",
      "customerIdentificationNumber": "32123456"
   }
}

Respuesta:

Se obtiene un JSON con los siguientes campos:

Ejemplo de respuesta:

{
  "status": "200",
  "code": "0",
  "message": "Success",
  "token": "33C021C23EEF3DB7148DD30DF1F75134C89648FEBA505029443F48CC5E10C371"
}

2.1.1.2 Autorización de Pago

POST

Servicio: /web-vtol/service/v2/authorizeForm

Una vez generado y almacenado el token de acceso, se deberá ejecutar la Autorización de pago, utilizando en esta instancia el token previamente generado.

Invocación:

Al invocar a este servicio, VPB desplegará una ventana segura con el formulario de pago para capturar los datos de la tarjeta.

Se envían los siguientes parámetros de la operación dentro de la URL:

Ejemplo:

https://localhost:8843/web-vtol/service/v2/authorizeForm.html?token=33C021C23EEF3DB7148DD30DF1F75134C89648FEBA505029443F48CC5E10C371

Respuesta:

La respuesta se realiza en la dirección de callback especificada por el eCommerce.

Se responden los siguientes campos:

Ejemplo de respuesta:

{
   "transactionType": "Sale",
   "ecommerce": {
      "company": "C1",
      "store": "1"
   },
   "transactionId": "1580408171332",
   "responseCode": "00",
   "status": "Pending"
}

2.1.1.3 Intención de Pago PEI

VTOL Payment Bridge ofrece la posibilidad de realizar Pagos PEI (Pago Electrónico Inmediato), con tarjeta de débito. Estas operaciones se transfieren desde la cuenta del cliente a la cuenta del Comercio y se acreditan de manera instantánea. Dichos pagos serán autorizados por Red LINK.

POST

Servicio: /web-vtol/service/v2/paymentIntention

La intención de pago es el primer paso necesario para ejecutar una transacción de pago PEI entre un comercio y la API REST de VPB. Como resultado se obtiene un Token de acceso para poder cursar el pago.

Invocación:

En el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

En el POST enviar el atributo transactionType=SalePEI.

Validaciones del campo identificationNumberMatch:

• • Si el valor enviado por el eCommerce y el valor ingresado por el usuario en el formulario de VPB coinciden, entonces se enviará la transacción a VTOL Sever para ser autorizada.
  • Si el valor enviado por el eCommerce y el valor ingresado por el usuario en el formulario de VPB NO coinciden, entonces se mostrará el siguiente mensaje en pantalla: "Algo salió mal. Ingrese nuevamente los datos". Se mostrará el formulario de VPB con todos los campos en blanco para que se vuelvan a cargar. Sólo se podrá ingresar 3 veces un valor no coincidente. Al cuarto intento que no coinciden los DNI, se retornará a la url de callbackError al eCommerce, informando el error "Excedió el número de reintentos". Estos intentos se sumarizan junto a los errores que valida VPB antes de enviar la transacción a VTOL Server. Ver Validaciones en el formulario VPB
    
    

Ejemplo de requerimiento:

{
   "ecommerce": {
      "company": "100",
      "store": "101"
   },
   "paymentData": {
      "payments": "1",
      "plan": "0"
   },
   "validationData": {
      "identificationNumberMatch": true
   },
   "transactionType": "salePEI",
   "autoCommit": "false",
   "additionalCardHolder": "false",
   "transactionId": "20201027122637",
   "orderDescription": "El total de su compra es de $110.99. Ha elegido pagar en Pesos Argentinos (ARS)",
   "amount": "110.90",
   "currency": "$",
   "posTicket": "",
   "ecommerceCustomField": "",
   "cardHolder": {
      "identificationType": "2",
      "identificationNumber": "12345678",
      "birthdate": "01/10/2001",
      "phone": "",
      "deliveryAddress": {
         "streetName": "Venezuela",
         "streetNumber": "3158",
         "complement": "Edificio Lumina",
         "zipCode": "B1603"
      }
   },
   "url": {
      "callbackUrlError": "http://localhost:8280/emulatorEcommerce/callbackErrorURL.jsp",
      "callbackUrlSuccessful": "http://localhost:8280/emulatorEcommerce/callbackOKURL.jsp",
      "callbackUrlCancel": "http://localhost:8280/emulatorEcommerce/callBackCancel.jsp",
      "checkTransactionStatus": "http://localhost:8280/emulatorEcommerce/service/checkStatusReturnRandom.html"
   },
   "formData": {
      "merchantName": "",
      "merchantImageURL": "",
      "merchantImageMobileURL": ""
   },
   "cardValidation": {
      "brand": "Visa",
      "provider": "EL"
   },
   "customerData": {
      "customerId": "100",
      "customerIP": "10.90.100.101",
      "customerName": "NOMBRE25",
      "customerLastName": "APELLIDO25",
      "customerIdentificationType": "2",
      "customerIdentificationNumber": "34000499"
   }
}

Respuesta:

Se obtiene un JSON con los siguientes campos:

Ejemplo de respuesta:

{
  "status": "200",
  "code": "0",
  "message": "Success",
  "token": "33C021C23EEF3DB7148DD30DF1F75134C89648FEBA505029443F48CC5E10C371"
}

2.1.1.4 Autorización de Pago PEI

POST

Servicio: /web-vtol/service/v2/authorizeForm

Una vez generado y almacenado el token de acceso, se deberá ejecutar la Autorización de pago PEI, utilizando en esta instancia el token previamente generado.

Invocación:

Al invocar a este servicio, VPB desplegará una ventana segura con el formulario de pago para capturar los datos de la tarjeta.

Se envían los siguientes parámetros de la operación dentro de la URL:

Ejemplo:

https://localhost:8843/web-vtol/service/v2/authorizeForm.html?token=33C021C23EEF3DB7148DD30DF1F75134C89648FEBA505029443F48CC5E10C371

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:

2.1.1.5 Consultar Estado de Transacción

GET

Servicio: /web-vtol/service/v2/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 el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

Se envían los siguientes parámetros dentro de la URL:

Ejemplo:

{
   "transactionId": "1580409092436",
   "ecommerce": {
      "company": "C1",
      "store": "1"
   }
}

Respuesta de operación de Crédito

La respuesta retorna los siguientes campos:

Los campos se responden en formato json "Nombre del campo":"valor"

Ejemplo de respuesta:

{ 
   "company":"C1",
   "amount":"100.00",
   "providerCode":"VI"
   "providerName":"Visa",
   "ticket":"4",
   "authorizationCode":"123456",
   "store":"1",
   "transactionDate":"2020-01-30 15:31:57.417",
   "authorizationStatus":"Pending",
   "responseCode":"00",
   "node":"0000000001",
   "displayMessage":"prueba de impresion",
   "currency":"$",
   "transactionId":114,
   "responseMessage":"APROBADA",
   "vtolTrxId":"30012015321300000110",
   "maskedCardNumber":"4540******0010"
}

Respuesta de operación PEI

La respuesta retorna los siguientes campos:

Ejemplo de respuesta:

{ 
   "company":"C1",
   "store":"1",
   "amount":"100.00",
   "providerCode":"EL",
   "providerName":"Visa Electron",
   "transactionDate":"2020-01-30 15:31:57.417",
   "authorizationStatus":"Commit",
   "responseCode":"00",
   "responseMessage":"APROBADA"
   "node":"0000000001",
   "displayMessage":"prueba de impresion",
   "currency":"$",
   "transactionId":114,
   "trxReferenceNumber":"30012015321300000110",
   "idOperationPEI":"7589999999999999758",
   "bankingRefNum":"123456",
   "idCommercePEI":"SYN01",
   "idBranchPEI":"RSYN",
   "maskedCardNumber":"4507******0010"
}

2.1.1.6 Cierre de Transacción

POST

Servicio: /web-vtol/service/v2/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 el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

Se envían los siguientes parámetros de la operación:

Ejemplo:

{
   "transactionId": "1580408171332",
   "ecommerce": {
      "company": "C1",
      "store": "1"
   },
   "action": "commit"
}

Respuesta:

La respuesta sólo retorna un código HTTP 200.

2.1.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 pre-autorización, y luego se genera la captura. Son operaciones llamadas de dos fases.

La pre-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.

2.1.2.1 Intención de Pago

POST

Servicio: /web-vtol/service/v2/paymentIntention

La intención de pago es el primer paso necesario para ejecutar una transacción de pago entre un comercio y la API REST de VPB. Como resultado se obtiene un Token de acceso para poder cursar el pago.

El pedido de pre-autorización es un servicio que valida la información de la tarjeta que se envía, para verificar si es posible continuar con el proceso de pago y reservar los fondos del tarjeta habiente.

Invocación:

En el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

Para realizar una intención de pago en 2 fases, en el POST enviar el atributo transactionType=authorization.

* 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": "2",
      "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": "2",
      "customerIdentificationNumber": "32123456"
   }
}

Respuesta:

Se obtiene un JSON con los siguientes campos:

Ejemplo de respuesta:

{
  "status": "200",
  "code": "0",
  "message": "Success",
  "token": "33C021C23EEF3DB7148DD30DF1F75134C89648FEBA505029443F48CC5E10C371"
}

2.1.2.2 Autorización de Pago

POST

Servicio: /web-vtol/service/v2/authorizeForm

Una vez generado y almacenado el token de acceso, se deberá ejecutar la Autorización de pago, utilizando en esta instancia el token previamente generado.

Invocación:

Al invocar a este servicio, VPB desplegará una ventana segura con el formulario de pago para capturar los datos de la tarjeta.

Se envían los siguientes parámetros de la operación dentro de la URL:

Ejemplo:

https://localhost:8843/web-vtol/service/v2/authorizeForm.html?token=33C021C23EEF3DB7148DD30DF1F75134C89648FEBA505029443F48CC5E10C371

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:

Ejemplo de respuesta:

{
   "transactionType": "Authorization",
   "ecommerce": {
      "company": "C1",
      "store": "13"
   },
   "transactionId": "1581605477722",
   "responseCode": "00",
   "status": "Pending"
}

2.1.2.3 Consultar Estado de Transacción

GET

Servicio: /web-vtol/service/v2/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.

Invocación:

La invocación a este servicio es el mismo que en las operaciones de una fase: Consultar Estado de Transacción

En el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

2.1.2.4 Captura de Pago

POST

Servicio: /web-vtol/service/v2/closeTransaction

Esta operatoria se utiliza exclusivamente luego de haber realizado un Pedido de Pre-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. 

Invocación:

En el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

Se envían los siguientes parámetros con los datos de la captura:

Ejemplo:

{
   "transactionId": "1581605477722",
   "ecommerce": {
      "company": "C1",
      "store": "13"
   },
   "action": "commit"
}

Respuesta:

La respuesta sólo retorna un código HTTP 200.

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.

Invocación:

En el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

En la invocación POST se envían los siguientes parámetros con los datos de la captura:

Ejemplo:

{
   "transactionId": "1581605477722",
   "ecommerce": {
      "company": "C1",
      "store": "13"
   },
   "amount":500.22,
   "action": "commit"
}

Respuesta:

La respuesta sólo retorna un código HTTP 200.

2.1.2.5 Cancelar una Autorización de Pago

POST

Servicio: /web-vtol/service/v2/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.

Invocación:

En el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

Se envían los siguientes parámetros con los datos de la cancelación:

Ejemplo:

{
   "transactionId": "1581605477722",
   "ecommerce": {
      "company": "C1",
      "store": "13"
   },
   "action": "rollback"
}

Respuesta:

La respuesta sólo retorna un código HTTP 200.

2.1.3 Devoluciones

VTOL Payment Bridge ofrece la posibilidad de realizar devoluciones de un pago y también de pagos PEI.

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.

2.1.3.1 Realizar devolución total del pago

POST

Servicio: /web-vtol/service/v2/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:

En el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

2.1.3.2 Realizar devolución parcial del pago

POST

Servicio: /web-vtol/service/v2/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).

Invocación:

En el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

Se debe indicar el monto a devolver, en el campo amount.

Respuesta:

La respuesta, tanto para devolución total como parcial, se realiza en la dirección de callback, especificada por el eCommerce en la operación de devolución.

Se responden los siguientes campos:

Ejemplo:

{
   "transactionId": "1581607736373",
   "transactionType": "Refund",
   "ecommerce": {
      "company": "C1",
      "store": "14"
   }
}

2.1.3.3 Cierre de transacción

Servicio: /web-vtol/service/v2/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.

POST

Invocación:

En el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

Se envían los siguientes parámetros de la operación:

Ejemplo:

{
   "transactionId": "11445878985",
   "ecommerce": {
      "company": "1",
      "store": "1"
   },
   "action": "commit"
}

Respuesta:

La respuesta sólo retorna un código HTTP 200.

2.1.3.4 Realizar devolución total de pago PEI

POST

Servicio: /web-vtol/service/v2/refunds

Se debe invocar un método POST a la URL de VPB, enviando el atributo transactionType=refundPEI.

Si no se informa el monto, la devolución se hará por el total de la orden.

Invocación:

En el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

2.1.3.5 Realizar devolución parcial de pago PEI

POST

Servicio: /web-vtol/service/v2/refunds

Se debe invocar un método POST a la URL de VPB, enviando el atributo transactionType=refundPEI.

Es posible realizar devoluciones parciales (incluso más de una por orden, siempre y cuando no se supere el monto de la misma).

Invocación:

En el Header se envían las credenciales usuario y contraseña de autenticación HTTP Basic

Se debe indicar el monto a devolver, en el campo amount.

Respuesta:

La respuesta, tanto para devolución total como parcial, se realiza en la dirección de callback, especificada por el eCommerce en la operación de devolución.

Se responden los siguientes campos:

Ejemplo:

{
   "transactionId": "1581607736373",
   "transactionType": "Refund",
   "ecommerce": {
      "company": "C1",
      "store": "12"
   }
}

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

2.2.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:

Ejemplo:

https://www.e-commerce.com/service/getTransactionStatus.html?transactionId=1567105313489&company=1&store=1

Respuesta:

La respuesta retornará los siguientes campos:

Los campos se responden en formato json "Nombre del campo":"valor"

Ejemplo de respuesta:

200:{
	"company":"1",
	"store":"1",	
	"transactionId":"1567105313489",
	"status":"Commit"
}

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

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

2.3.2 Códigos de respuesta por validación en VPB

2.3.3 Códigos de respuesta de VTOL Server para PEI

A continuación se detallan las respuestas posibles de VTOL Server, cuando se opera con PEI:

3. Flujo transaccional

A continuación se detallan los diagramas de secuencia de cada tipo de operación.

3.1 Transacciones simples (de 1 fase)

3.2 Transacciones en dos fases

3.3 Devoluciones