...
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. |
16/09/2020 | 1.5 | Agregado de operaciones PEI. Pago PEI, Consulta, y Devoluciones PEI. |
Índice
Índice
Âncora_Toc434487091 _Toc434487091
1. Introducción
_Toc434487091 | |
_Toc434487091 |
...
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, Tipo y Número de Documento, y Dirección 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
Âncora_Toc434487094 _Toc434487094
1.3 Ventajas
_Toc434487094 | |
_Toc434487094 |
...
Âncora_Toc434487099 _Toc434487099
1.6 Alta disponibilidad
_Toc434487099 | |
_Toc434487099 |
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 _validacionesEnVpb _validacionesEnVpb
1.7 Validaciones en el formulario VPB
_validacionesEnVpb | |
_validacionesEnVpb |
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 Titular de al 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 seguir ingresando ingresar los datos de la tarjeta. En el cuarto intento, VPB hará una redirección a la URL de Callback ErrorCallbackError, informando el error al eCommerce.
...
Âncora_Toc434487108 _Toc434487108
2. Integración
_Toc434487108 | |
_Toc434487108 |
En esta sección se detalla la manera de integrar el e-commerce con VTOL Payment Bridge.
Informações | ||
---|---|---|
| ||
El formulario de pago para capturar los datos de la tarjeta se desplegará únicamente cuando se invoque a los servicios de Autorización de Pago (ya sea en una fase o en dos fases). Los demás servicios, como ser Consulta de estado, Cancelación, Devolución, no desplegarán ningún formulario. La API de VPB retornará una respuesta con un status code según cada invocación, las cuales están descritas en los siguientes apartados. |
...
Las operaciones disponibles son:
- Operaciones con tarjetas de crédito-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
- Transacción en 1 fase
Operaciones con tarjeta de crédito-débito
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 autoriza, 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 Autorización de Pago
Servicio: /web-vtol/service/authorizeForm
...
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 | Alfanumé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 | SI | Opciones de pago. | ||
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. |
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 DDMMYYYY. 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. Longitud máxima 30. | ||
customerLastName | Alfanumérico | NO | Apellido del cliente del e-commerce. Longitud máxima 30. | ||
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. |
* 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:
...
theme | Midnight |
---|---|
title | json |
linenumbers | true |
...
validationData | Object | NO | Colección para informar los campos que VPB validará si coinciden con los datos ingresados por el usuario en el formulario. | ||
identificationNumberMatch | Boolean | NO | Indica si el campo identificationNumber de la colección cardHolder, debe validar coincidencia entre el dato enviado por el eCommerce y valor ingresado por el cliente en el formulario de VPB. True: VPB verificará si coinciden los datos. Ver validaciones del campo. False: VPB no verificará si coinciden los datos. Si el eCommerce no envía este campo, entonces VPB no realizará ninguna verificación. |
* 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:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "ecommerce": { "company": "1C1", "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": "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" } } |
...
Se responden los siguientes campos:
Parámetro | Tipo | Descripción | |
---|---|---|---|
transactionType | Alfanumérico | Tipo de transacción realizada. | |
ecommerce | Object | Datos del comercio electrónico | |
company | Alfanumé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. | |
responseCode | Numérico | Código de respuesta de la operación realizada. | |
status | Alfanumérico | Estado en el cual quedó registrada de la transacción realizada. |
Informações | ||
---|---|---|
| ||
Cuando el eCommerce recibe la notificaciónel callback, tiene que obtener la información completa del recurso notificado, accediendo al endpoint correspondiente de consulta de la API: |
...
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "transactionType": "Sale", "ecommerce": { "company": "C1", "store": "1" }, "transactionId": "1580408171332", "responseCode": "00", "status": "Pending" } |
...
2.1.1.2
...
Autorización de
...
Servicio: /web-vtol/service/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 dentro de la URL:
...
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.
Nota | ||
---|---|---|
| ||
Los pagos PEI tienen un tope límite diario para el consumidor final. Para compra de bienes, se podrán realizar por un importe acumulado diario que no exceda el equivalente a 5 veces el Salario Mínimo Vital y Móvil. Esta validación es realizada por Red LINK. |
Servicio: /authorizeForm
Para realizar una solicitud de Pago PEI, se debe invocar un método POST al endpoint de VPB, enviando el atributo transactionType=SalePEI.
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 | Alfanumé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 |
...
theme | Midnight |
---|---|
title | json |
linenumbers | true |
...
{
"transactionId": "1580409092436",
"ecommerce": {
"company": "C1",
"store": "1"
}
}
...
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
...
authorizationStatus
...
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.
...
id
...
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:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"amount":"100.00",
"providerCode":"Visa",
"ticket":"4",
"authorizationCode":"123456",
"store":"1",
"transactionDate":"2020-01-30 15:31:57.417",
"authorizationStatus":"Pending",
"responseCode":"00",
"node":"0000000001",
"displayMessage":"esta es una prueba de impresion",
"currency":"$",
"company":"C1",
"id":114,
"responseMessage":"APROBADA",
"vtolTrxId":"30012015321300000110"
} |
...
Servicio: /web-vtol/service/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
...
action
...
Alfanumérico
...
SI
...
commit: Confirmada
rollback: Cancelada
Los campos se envían en formato json "Nombre del campo":"valor"
Ejemplo:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"transactionId": "1580408171332",
"ecommerce": {
"company": "C1",
"store": "1"
},
"action": "commit"
} |
...
La respuesta sólo retorna un código HTTP 200.
Informações | ||
---|---|---|
| ||
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. |
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 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.
2.1.2.1 Autorización de Pago
Servicio: /web-vtol/service/authorizeForm
El pedido de 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.
Para realizar una autorización en dos fases, se debe invocar un método POST a la URL de VPB, enviando el atributo transactionType=authorization.
Invocación:
Al invocar a este servicio, VPB desplegará una ventana segura con el formulario de pago para capturar los datos de la tarjeta.
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
...
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.
...
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.
...
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.
...
Tipo de identificación. Valores posibles:
0: CUIT
1: CUIL
2: Número único
Obligatorio si additionalCardHolder=False
...
Número de identificación. Máximo 8 dígitos.
Obligatorio si additionalCardHolder=False
...
birthdate
...
Fecha de nacimiento del tarjeta habiente. Formato DDMMYYYY.
Obligatorio si additionalCardHolder=False
...
deliveryAddress
...
streetName
...
Calle.
Obligatorio si additionalCardHolder=False
...
streetNumber
...
Número de puerta.
Obligatorio si additionalCardHolder=False
...
zipCode
...
currency
...
Alfanumérico
...
SI
...
Tipo de Moneda:
- $ = Pesos
- U$S = Dólares
...
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.
Importante: que haya sido enviado a VTOL Server no significa que la operación se encuentre Aprobada.
...
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
...
merchantName
...
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
...
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.
...
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.
...
* 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:
...
theme | Midnight |
---|---|
title | json |
linenumbers | true |
...
SI | Tipo de transacción. Enviar: SalePEI | ||||
transactionId | Numérico | SI | Identificador de la transacción de pago. 16 dígitos de longitud. Debe ser generado por el eCommerce para identificar unívocamente 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. | ||
additionalCardHolder | Boolean | NO | Campo que podrá enviar el eCommerce para que VPB solicite datos adicionales del tarjeta habiente en el formulario de pago, y ser validados por antifraude. Estos datos serán enviados en el objeto cardHolder. Valores posibles: True: VPB solicitará 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. | ||
identificationType | Alfanumérico | NO | Tipo de identificación. Valores posibles: 0: CUIT | ||
identificationNumber | Numérico | NO | Número de identificación. Máximo 8 dígitos. | ||
birthdate | Date | Condicional | Fecha de nacimiento del tarjeta habiente. Formato DDMMYYYY. 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. Longitud máxima 30. | ||
customerLastName | Alfanumérico | NO | Apellido del cliente del e-commerce. Longitud máxima 30. | ||
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:
| ||
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. | ||
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. | ||
validationData | Object | NO | Colección para informar los campos que VPB validará si coinciden con los datos ingresados por el usuario en el formulario. | ||
identificationNumberMatch | Boolean | NO | Indica si el campo identificationNumber de la colección cardHolder, debe validar coincidencia entre el dato enviado por el eCommerce y valor ingresado por el cliente en el formulario de VPB. True: VPB verificará si coinciden los datos. Ver validaciones del campo. False: VPB no verificará si coinciden los datos. Si el eCommerce no envía este campo, entonces VPB no realizará ninguna verificación. |
Validaciones del campo identificationNumberMatch: Âncora identificationNumberMatch 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
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 | |
---|---|---|---|
transactionType | Alfanumérico | Tipo de transacción realizada. | |
ecommerce | Object | Datos del comercio electrónico | |
company | Alfanumé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. | |
responseCode | Numérico | Código de respuesta de la operación realizada. | |
status | Alfanumérico | Estado en el cual quedó registrada de la transacción realizada. |
Informações | ||
---|---|---|
| ||
Cuando el eCommerce recibe el callback, tiene que obtener la información completa del recurso, accediendo al endpoint de consulta de la API: Ante una falla en la respuesta, si el eCommerce no recibe el callback de VPB, tendrá que consultar el estado de la transacción, accediendo al endpoint de consulta: Dado que las operaciones PEI una vez que fueron aprobadas no permiten reversar, para poder llevar a cabo esta acción, el comercio deberá generar una operación de devolución (RefundPEI). |
Âncora | ||||
---|---|---|---|---|
|
Servicio: /web-vtol/service/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 dentro de la URL:
Campo | Tipo | Obligatorio | Descripción | |
---|---|---|---|---|
transactionId | Numérico | SI | Identificador de la transacción de pago generado por el ecommerce. | |
ecommerce | Object | SI | Datos del comercio electrónico | |
company | Alfanumé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. |
Ejemplo:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"transactionId": "1580409092436",
"ecommerce": {
"company": "C1",
"store": "1"
}
} |
Respuesta de operación de crédito
La respuesta retorna los siguientes campos:
Campo | Tipo | Descripción |
---|---|---|
company | Alfanumérico | Código de la compañía que realizó la transacción. |
store | Numérico | Código de la tienda asociada a la compañía que realizó la transacció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 |
authorizationStatus | Alfanumérico | Estado de la transacción. Puede ser: Initialized: Inicializado. Cancel: Cancelada por el usuario. Authorize: Autorizando. Rejected: Rechazada. Pending: Pendiente de confirmación. (No disponible para operaciones PEI) Commit: Confirmada. Rollback: Cancelada. (No disponible para operaciones PEI) |
node | Numérico | Código de nodo de VTOL Server utilizado para la autorización. |
id | 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 la tarjeta. |
providerName | Alfanumérico | Descripción de la tarjeta. |
displayMessage | Alfanumérico | Mensaje adicional enviado por el autorizador y que debe ser visualizado. |
transactionDate | Alfanumérico | Fecha y hora de la transacción. |
trxReferenceNumber | 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. |
cardNumber | Alfanumérico | Número de tarjeta del pago. Estará enmascarado. Por ejemplo: 4507******0010 |
payments | Numérico | Cantidad de cuotas |
Los campos se responden en formato json "Nombre del campo":"valor"
Ejemplo de respuesta:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"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":"$",
"company":"C1",
"id":114,
"responseMessage":"APROBADA",
"vtolTrxId":"30012015321300000110",
"cardNumber":"4540******0010"
} |
Respuesta de operación PEI
La respuesta retorna los siguientes campos:
Campo | Tipo | Descripción |
---|---|---|
company | Alfanumérico | Código de la compañía que realizó la transacción. |
store | Numérico | Código de la tienda asociada a la compañía que realizó la transacció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 |
authorizationStatus | Alfanumérico | Estado de la transacción. Puede ser: Initialized: Inicializada. Cancel: Cancelada por el usuario. Authorize: Autorizando. Rejected: Rechazada. Commit: Confirmada |
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. |
authorizationCode | Numérico | Código de autorización de la transacción, en caso de que haya sido aprobada. |
providerCode | Alfanumérico | Código de la tarjeta. |
providerName | Alfanumérico | Descripción de la tarjeta. |
displayMessage | Alfanumérico | Mensaje adicional enviado por el autorizador y que debe ser visualizado. |
transactionDate | Alfanumérico | Fecha y hora de la transacción. |
trxReferenceNumber | 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. |
idOperationPEI | Numérico | Identificador de la operación PEI de pago o de devolución, retornada por el autorizador. |
bankingRefNum | Numérico | Número de referencia bancaria de la operación. Es retornada por Red Link en la operación de pago y devolución. |
cardNumber | Alfanumérico | Número de tarjeta del pago. Estará enmascarado, el largo total coincide con la tarjeta. Por ejemplo: 4507******0010 |
peiCommerce | Alfanumérico | Número de comercio PEI de la transacción. |
peiTerminal | Alfanumérico | Número de terminal PEI de la transacción. |
Ejemplo de respuesta:
Bloco de código | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{
"company":"C1",
"store":"1",
"amount":"100.00",
"providerCode":"EL",
"providerName":"Visa Electron",
"transactionDate":"2020-01-30 15:31:57.417",
"authorizationStatus":"Commit",
"responseCode":"00",
"message":"APROBADA"
"node":"0000000001",
"displayMessage":"prueba de impresion",
"currency":"$",
"transactionId":114,
"responseMessage":"APROBADA",
"trxReferenceNumber":"30012015321300000110",
"idOperationPEI":"7589999999999999758",
"bankingRefNum":"123456",
"cardNumber":"4507******0010",
"peiCommerce":"SYN01",
"peiTerminal":"0011"
} |
2.1.1.4 Cierre de Transacción
Servicio: /web-vtol/service/closeTransaction
VPB permite cerrar la transacción para confirmarla o cancelarla, a través de un método POST a la URL de VPB.
Nota | ||
---|---|---|
| ||
Para Operaciones PEI, el Cierre de Transacción no aplica. Es decir, no se debe invocar esta acción, ya que las operaciones PEI quedan confirmadas automáticamente. Si VPB responde que la operación PEI resultó Aprobada, dicha operación quedará en status commit. |
Invocación:
En la invocación POST 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. | |
ecommerce | Object | SI | Datos del comercio electrónico | |
company | Alfanumé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. | |
action | Alfanumérico | SI | commit: Confirmada rollback: Cancelada |
Los campos se envían en formato json "Nombre del campo":"valor"
Ejemplo:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "transactionId": "1580408171332", "ecommerce": { "company": "C1", "store": "1" }, "customerDataaction": { "customerId": "100", "customerIP": "10.90.100.101", "customerName": "Juan Carlos","commit" } |
Respuesta:
La respuesta sólo retorna un código HTTP 200.
Informações | ||
---|---|---|
| ||
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. |
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 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.
Nota | ||
---|---|---|
| ||
Para Operaciones PEI, las transacción en 2 fases no aplica. Las operaciones PEI sólo se podrán hacer en 1 fase. |
2.1.2.1 Autorización de Pago
Servicio: /web-vtol/service/authorizeForm
El pedido de 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.
Para realizar una autorización en dos fases, se debe invocar un método POST a la URL de VPB, enviando el atributo transactionType=authorization.
Invocación:
Al invocar a este servicio, VPB desplegará una ventana segura con el formulario de pago para capturar los datos de la tarjeta.
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 | Alfanumé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. | ||
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 DDMMYYYY. 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. | ||
validationData | Object | NO | Colección para informar los campos que VPB validará si coinciden con los datos ingresados por el usuario en el formulario. | ||
identificationNumberMatch | Boolean | NO | Indica si el campo identificationNumber de la colección cardHolder, debe validar coincidencia entre el dato enviado por el eCommerce y valor ingresado por el cliente en el formulario de VPB. True: VPB verificará si coinciden los datos. False: VPB no verificará si coinciden los datos. Si el eCommerce no envía este campo, entonces VPB no realizará ninguna verificación. |
* 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:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"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 | |
---|---|---|---|
transactionType | Alfanumérico | Tipo de transacción. | |
ecommerce | Object | Datos del comercio electrónico | |
company | Alfanumé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. | |
responseCode | Numérico | Código de respuesta de la operación realizada. | |
status | Alfanumérico | Estado en el cual quedó registrada de la transacción realizada. |
Los campos se envían en formato json "Nombre del campo":"valor"
Informações | ||||
---|---|---|---|---|
| ||||
Cuando el eCommerce recibe la notificación, tiene que obtener la información completa del recurso notificado, accediendo al endpoint correspondiente de la API: |
Ejemplo de respuesta:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"transactionType": "Authorization",
"ecommerce": {
"company": "C1",
"store": "13"
},
"transactionId": "1581605477722",
"responseCode": "00",
"status": "Pending"
} |
Informações | ||
---|---|---|
| ||
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. |
2.1.2.2 Consultar Estado de Transacción
Servicio: /web-vtol/service/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
2.1.2.3 Captura de Pago
Servicio: /web-vtol/service/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.
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 | |
---|---|---|---|---|
transactionId | Numérico | SI | Identificador de la transacción de pago generado por el eCommerce. | |
ecommerce | Object | SI | Datos del comercio electrónico | |
company | Alfanumé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. | |
action | Alfanumérico | SI | Valores posibles: commit: Confirmada |
Ejemplo:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"transactionId": "1581605477722",
"ecommerce": {
"company": "C1",
"store": "13"
},
"action": "commit"
} |
Respuesta:
La respuesta sólo retorna un código HTTP 200.
Informações | ||
---|---|---|
| ||
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.
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 | |
---|---|---|---|---|
transactionId | Numérico | SI | Identificador de la transacción de pago generado por el eCommerce. | |
ecommerce | Object | SI | Datos del comercio electrónico | |
company | Alfanumé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. | |
amount | Numérico | SI | Importe definitivo de la venta. | |
action | Alfanumérico | SI | Valores posibles: commit: Confirmada |
Ejemplo:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"transactionId": "1581605477722",
"ecommerce": {
"company": "C1",
"store": "13"
},
"amount":500.22,
"action": "commit"
} |
Respuesta:
La respuesta sólo retorna un código HTTP 200.
Informações | ||
---|---|---|
| ||
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. |
2.1.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.
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 | |
---|---|---|---|---|
transactionId | Numérico | SI | Identificador de la transacción de pago generado por el eCommerce. | |
ecommerce | Object | SI | Datos del comercio electrónico | |
company | Alfanumé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. | |
action | Alfanumérico | SI | Enviarrollback: Cancelar autorización |
Los campos se envían en formato json "Nombre del campo":"valor"
Ejemplo:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "transactionId": "1581605477722", "ecommerce": { "customerLastNamecompany": "MessiC1", "customerIdentificationTypestore": "113", }, "customerIdentificationNumberaction": "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
...
Numérico
...
Los campos se envían en formato json "Nombre del campo":"valor"
Informações | ||||
---|---|---|---|---|
| ||||
Cuando el eCommerce recibe la notificación, tiene que obtener la información completa del recurso notificado, accediendo al endpoint correspondiente de la API: |
Ejemplo de respuesta:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"transactionType": "Authorization",
"ecommerce": {
"company": "C1",
"store": "13"
},
"transactionId": "1581605477722",
"responseCode": "00",
"status": "Pending"
} |
Informações | ||
---|---|---|
| ||
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. |
2.1.2.2 Consultar Estado de Transacción
Servicio: /web-vtol/service/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
2.1.2.3 Captura de Pago
Servicio: /web-vtol/service/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.
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
...
transactionId
...
Numérico
...
SI
...
Identificador de la transacción de pago generado por el eCommerce.
...
action
...
Alfanumérico
...
SI
...
Valores posibles:
commit: Confirmada
rollback: Cancelada
Ejemplo:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"transactionId": "1581605477722",
"ecommerce": {
"company": "C1",
"store": "13"
},
"action": "commit"
} |
...
La respuesta sólo retorna un código HTTP 200.
Informações | ||
---|---|---|
| ||
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.
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
...
transactionId
...
Numérico
...
SI
...
Identificador de la transacción de pago generado por el eCommerce.
...
rollback"
} |
Respuesta:
La respuesta sólo retorna un código HTTP 200.
Informações | ||
---|---|---|
| ||
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. |
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
Servicio: /web-vtol/service/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 | Alfanumé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 |
2.1.3.2 Realizar devolución parcial del pago
Servicio: /web-vtol/service/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 | Alfanumé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 |
action
Alfanumérico
SI
Valores posibles:
commit: Confirmada
rollback: Cancelada
Ejemplo:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"transactionId": "1581605477722",
"ecommerce": {
"company": "C1",
"store": "13"
},
"amount":500.22,
"action": "commit"
} |
...
La respuesta sólo retorna un código HTTP 200.
Informações | ||
---|---|---|
| ||
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. |
2.1.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.
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
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, 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:
Parámetro | Tipo | Descripción | |
---|---|---|---|
transactionId | Numérico |
SI
Identificador de la transacción de |
devolución generado por el eCommerce. | |||
transactionType | Alfanumérico | Tipo de transacción: Refund | |
ecommerce | Object |
Datos del comercio electrónico | |
company |
Alfanumé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. |
Informações |
---|
...
|
...
SI
...
| |
Cuando el eCommerce recibe el callback, tiene que obtener la información completa del recurso, accediendo al endpoint de consulta de la API: |
Ejemplo:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "transactionId": "15816054777221581607736373", "ecommercetransactionType": {"Refund", "companyecommerce": "C1",{ "storecompany": "13C1", }, "action": "rollback" } |
...
La respuesta sólo retorna un código HTTP 200.
Informações | ||
---|---|---|
| ||
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. "store": "14"
}
} |
2.1.3
...
VTOL Payment Bridge ofrece la posibilidad de realizar devoluciones de un pago.
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
.3 Cierre de transacción
Servicio: /web-vtol/service/refundsSe debe invocar /service/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, 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:
...
. Esta operación se debe llevar a cabo para poder cerrar la transacción.
Nota | ||
---|---|---|
| ||
Para Operaciones PEI, el Cierre de Transacción no aplica. Es decir, no se debe invocar esta acción, ya que las operaciones PEI quedan confirmadas automáticamente. Si VPB responde que la operación PEI resultó Aprobada, dicha operación quedará en status commit. |
Invocación:
En la invocación POST 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. | |
ecommerce | Object | SI | Datos del comercio electrónico. | |
company |
Alfanumé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. |
...
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
...
Numérico
...
Informações | ||
---|---|---|
| ||
Cuando el eCommerce recibe la notificación, tiene que obtener la información completa del recurso notificado, accediendo al endpoint correspondiente de la API: |
Ejemplo:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"transactionType": "Refund",
"ecommerce": {
"company": "C1",
"store": "13"
},
"transactionId": "1581607736373"
} |
2.1.3.3 Cierre de transacción
Servicio: /web-vtol/service/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
transactionId
Numérico
SI
Identificador de la transacción de pago generado por el ecommerce.
action | Alfanumérico | SI |
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
2.1.3.2 Realizar devolución parcial del pago
Servicio: /web-vtol/service/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
.
...
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
...
commit: Confirmada rollback: Cancelada |
Los campos se envían en formato json "Nombre del campo":"valor"
Ejemplo:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"transactionId": "11445878985",
"ecommerce": {
"company": "1",
"store": "1"
},
"action": "commit"
} |
Respuesta:
La respuesta sólo retorna un código HTTP 200.
Informações | ||
---|---|---|
| ||
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. |
2.1.3.4 Realizar devolución total de pago PEI
Servicio: /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:
Parámetro | Tipo de dato | Obligatorio | Descripción | |
---|---|---|---|---|
ecommerce | Object | SI | Datos del comercio electrónico | |
company | Alfanumé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 refundPEI | |
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 | |
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. |
2.1.3.5 Realizar devolución parcial de pago PEI
Servicio: /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).
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 | Alfanumé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 refundPEI | |
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 | |
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. |
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:
Parámetro | Tipo | Descripción | |||
---|---|---|---|---|---|
transactionId | Numérico | Identificador de la transacción de devolución generado por el eCommerce. | |||
transactionType | Alfanumérico | Tipo de transacción: Refund | |||
ecommerce | Object | Datos del comercio electrónico | |||
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 | el cierre dela | transaccióncompra. | action
Informações |
---|
...
|
...
SI
...
commit: Confirmada
rollback: Cancelada
...
| |
Cuando el eCommerce recibe el callback, tiene que obtener la información completa del recurso, accediendo al endpoint de consulta de la API: |
Ejemplo:
Bloco de código | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{ "transactionId": "11445878985"1581607736373", "transactionType": "Refund", "ecommerce": { "company": "1C1", "store": "112" }, "action": "commit" } |
Respuesta:
La respuesta sólo retorna un código HTTP 200.
| ||
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. |
Âncora_Toc381043096 _Toc381043096
Âncora_Toc434487111 _Toc434487111
2.2 Servicios brindados por el E-Commerce
_Toc381043096 | |
_Toc381043096 |
_Toc434487111 | |
_Toc434487111 |
...
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 |
Alfanumé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:
Bloco de código | ||||
---|---|---|---|---|
| ||||
https://www.e-commerce.com/service/getTransactionStatus.html?transactionId=1567105313489&company=1&store=1 |
...
La respuesta retornará los siguientes campos:
Parámetro | Tipo | Descripción |
---|---|---|
company |
Alfanumé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"
...
Âncora_Códigos_de_respuesta _Códigos_de_respuesta
Âncora_Toc434487112 _Toc434487112
2.3 Códigos de Respuesta
_Códigos_de_respuesta | |
_Códigos_de_respuesta |
_Toc434487112 | |
_Toc434487112 |
VPB responde a cada transacción que recibe para autorizar con un código de respuesta y una descripción del mismo, indicando cual fue el resultado de la operación.
A continuación se detallan las respuestas posibles.
2.3.1 Códigos recibidos de VTOL Server
...