VTOL CD AR - Manual de mensajería POS - VTOL AR
VTOL CRÉDITO DÉBITO ARGENTINA
Mensajería POS - VTOL
...
| Painel | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
...
| Painel | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
Âncora _Toc485222713 _Toc485222713
1. Campos de los mensajes
| _Toc485222713 | |
| _Toc485222713 |
...
Número | Nombre del campo | Tipo de dato | SaleWallet | RefundWallet | QueryWallet | Descripción |
|---|---|---|---|---|---|---|
| 0 | company | Numérico | X | X | X | Identificador de la compañía donde se generó la transacción |
| 1 | store | Alfanumérico | X | X | X | Identificador del sitio originador de la transacción |
| 2 | node | Numérico | X | X | X | Identificación del nodo, en el sitio originador, donde se generó la transacción |
| 6 | cardNumber | Alfanumérico | O | - | O | Tarjeta enmascarada seleccionada al momento de efectuar el pago QR. El campo es opcional en caso de que se haya abonado con saldo de la cuenta de Mercado Pago. Para Rappi este campo no retorna. |
| 12 | amount | Importe | X | - | X | Monto de la transacción. Valor entero. Los últimos 2 dígitos corresponden a los decimales. |
| 13 | currencyPosCode | Alfanumérico | O | - | X | Tipos de moneda:
|
| 14 | payments | Numérico | - | - | O | Cantidad de cuotas seleccionadas al momento de realizar el pago QR. El campo es opcional en caso de que se haya abonado con saldo de la cuenta de Mercado Pago |
| 22 | authorizationCode | Alfanumérico | O | - | O | Código de autorización informado por el Autorizador. Para Mercado Pago sólo retorna cuando el cliente paga con tarjeta de crédito o débito. Para Yacaré este campo no retorna. |
| 24 | trxId | Numérico | X | X | X | Identificador de la transacción |
| 25 | dateTime | Numérico | X | X | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS. El valor en este campo debe ser el mismo que el valor de la fecha y hora del requerimiento. El POS utiliza este dato para validar que se trate de la misma transacción |
| 26 | responseCode | Alfanumérico | X | X | X | Puede contener uno de los siguientes valores:
|
| 27 | isoCode | Numérico | X | X | X | Código de Respuesta emitido por el centro autorizador. 3 dígitos como máximo. Ver sección Códigos de Respuesta de VTOL Server para Billeteras Electrónicas |
| 28 | responseMessage | Alfanumérico | X | X | X | Mensaje de la Respuesta relacionado con el código del campo 27 |
| 54 | additionalAmount | Importe | O | O | O | Contiene el Importe del "Cashout". Para aquellas operaciones realizadas con retiro de efectivo. Valor entero. Los últimos 2 dígitos corresponden a los decimales. Sólo disponible para billetera Mercado Pago. |
| 140 | paymentType | Numérico | - | - | X | Tipo de pago. Valores posibles: 0: Tarjeta |
| 142 | providerName | Alfanumérico | - | - | O | Proveedor de la tarjeta seleccionada al momento de efectuar el pago QR. El campo es opcional en caso de que se haya abonado con saldo de la cuenta de Mercado Pago |
| 147 | providerPosCode | Lista | O | - | - | Lista de proveedores/tarjetas que coinciden con la tarjeta ingresada en la app de la billetera electrónica. Ejemplo: {VI, EL}. Esta lista deberá ser utilizada para seleccionar la tarjeta manualmente por el POS. |
| 157 | customerDoc | Numérico | O | O | O | Numero de documento del titular de la tarjeta. |
| 303 | customerName | Alfanumérico | O | O | O | Nombre del titular de la tarjeta. |
| 166 | trxReferenceNumber | Numérico | X | X | X | Identificador único 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 |
| 271 | walletPaymentId | Alfanumérico | X | - | X | Identificador del número de pago informado por el Autorizador. Para Rappi, en este campo retorna el barcode utilizado para el pago. |
| 272 | amountRefunded | Importe | - | - | X | Monto devuelto en la transacción |
| 273 | paymentStatus | Alfanumérico | O | - | O | Estado de la transacción de pago informado por el Autorizador. Estados posibles: 0: Aprobado |
| 274 | paymentStatusDetail | Alfanumérico | O | - | O | Detalle del estado de la transacción de pago informado por el Autorizador. |
| 275 | cardType | Numérico | - | - | O | Tipo de tarjeta seleccionada al momento de efectuar el pago QR. Es opcional en caso de que se haya abonado con saldo de la cuenta de Mercado Pago. Para Yacaré este campo no retorna. Para Rappi este campo no retorna. Valores posibles: |
| 415 | walletPayoutId | Alfanumérico | O | - | O | Identificador del ID de cashback informado por el Autorizador. Sólo retorna en caso de haber realizado Retiro de efectivo con la app de Mercado Pago. |
Ejemplo
Response from VTOL (SaleWallet): Response message: {1:1;2:1;166:14021905052200000204;271:2289999999999999228;22:1234567;24:121;25:20190214050518;26:ISO8583;27:00;28:APROBADA} Response from VTOL (RefundWallet): Response message: {1:1;2:1;25:20190214050543;26:ISO8583;27:509;28:Estado trx original no acepta devolucion} Response from VTOL (QueryWallet): Response message: {1:1;2:1;6:450995xxxxxx3704;140:0;12:53.0;13:$;14:1;142:visa;271:2289999999999999228;272:0.0;273:0;274:accredited;275:1;22:1234567;24:121;25:20190214050534;26:ISO8583;27:00;28:APROBADA} |
...
VTOL se integra con QR Adquiriente de Fiserv para permitir efectuar pagos en los puntos de venta con billeteras electrónicas. En el pinpad se imprime el código QR en pantalla, el cual siempre es dinámico, es decir que se genera uno nuevo por cada transacción.
...
| Aviso | ||
|---|---|---|
| ||
En caso de ser un pago con Tarjeta de Débito, el POS deberá enviar en el mensaje SaleWallet el campo payments (14) con valor = 1. En caso de ser un pago con Tarjeta de Crédito, el POS deberá enviar en el mensaje SaleWallet el campo payments (14) con valor mayor a 0. En caso de ser un pago con Dinero en cuenta, el POS deberá enviar en el mensaje SaleWallet el campo payments (14) con valor = 0, o directamente no enviar el campo 14. Operatoria de pago con Tarjetas: El Punto de Venta informará en el mensaje de SaleWallet el Monto y las Cuotas de la operación. VTOL responderá al POS el dato de la tarjeta seleccionada por el cliente en su Billetera Virtual, y el POS con esa información podrá modificar o no el monto original y las cuotas originales. Esto es para que el POS pueda aplicar algún beneficio, por ejemplo 12 cuotas sin interés, o para aplicar intereses, por ejemplo 12 con interés, con el cual el monto puede afectarse. Por lo tanto, el POS enviará en el mensaje de QueryWallet el monto y las cuotas, pudiendo modificar ambos datos. El flujo es el siguiente:
|
1.4.26.1 Requerimiento
| Informações | ||
|---|---|---|
| ||
X = Obligatorio |
...
Número | Nombre del campo | Tipo de dato | SaleWallet | QueryWallet | Descripción | |||||
|---|---|---|---|---|---|---|---|---|---|---|
| 0 | company | Numérico | X | X | Identificador de la compañía donde se generó la transacción. | |||||
| 1 | store | Alfanumérico | X | X | Identificador del sitio originador de la transacción | |||||
| 2 | node | Numérico | X | X | Identificación del nodo, en el sitio originador, donde se generó la transacción | |||||
| 3 | server | Alfanumérico | X | X | Identificador del Server que procesará la transacción. (en el caso de VTOL será 'VTOL') | |||||
| 4 | messageType | Alfanumérico | X | X | Tipo de Mensaje:
| |||||
| 11 | trxType | Alfanumérico | X | X | Tipo de Transacción:
| |||||
| 12 | amount | Numérico | X | - | Monto de la transacción. 12 dígitos como máximo. Valor entero. Los dos últimos dígitos representan los decimales. Ej: "1000" equivale a "10.00". | |||||
| 13 | currencyPosCode | Alfanumérico | X | - | Tipos de moneda:
| |||||
| 16 | originalDate | Numérico | - | X | Fecha de realización de la compra con billetera electrónica en formato YYYYMMDD | |||||
| 24 | lastTrxId | Numérico | O | O | Utilizado cuando está activo el control transaccional. En este campo el POS debe enviar la última transacción procesada correctamente. | |||||
| 25 | dateTime | Numérico | X | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS | |||||
| 268 | walletPosTrxId | Alfanumérico | X | O | Identificador único de la transacción de billetera para la compañía. Es originado por el POS para realizar una compra con billetera. Formato: Opcional en QueryWallet: Se informa este campo o el campo walletPaymentId para localizar una transacción de compra. | |||||
| 269 | walletType | Numérico | X | X | Tipo de billetera por la cual se cursará la transacción en el POS. Opciones: 7: QR Adquiriente Fiserv | |||||
| 270 | posTicket | Alfanumérico | X | - | Información del ticket en formato xml y posteriormente transformado en Base 64. Ver sección Estructura del campo posTicket | |||||
| 271 | walletPaymentId | Alfanumérico | - | O | Identificador del número de pago informado por el Autorizador en el campo 271 de la respuesta de la operación SaleWallet. Opcional en QueryWallet: Se informa este campo o el campo walletPosTrxId para localizar una transacción de compra. | 401 | paymentMethodsData | Json | O | -|
Información de los planes de pago, en formato json. Requerido únicamente cuando el pago se realiza con Tarjeta de crédito o débito. Si el POS no informa este campo, solamente se podrá pagar con Dinero en cuenta. | 410 | QRCode | Alfanumérico | O | - | El POS enviará si desea recibir el código QR para imprimirlo en la caja. Valores posibles: True: indica que se recibirá el código QR y se inyectará en el pinpad. False: indica que se recibirá el código QR pero no se inyectará en el pinpad. No se envía el campo: indica que no se recibirá el código QR |
Estructura del campo posTicket (270)
El mensaje con la estructura del ticket estará en XML. El elemento raíz de ese mensaje XML deberá ser la etiqueta <message>, siendo la misma lo que se llamará encabezado.La manera de ejecutar un comando es utilizando una etiqueta con la forma <elemento-comando>. El elemento "item" identifica a los artículos. De esta manera
Dentro del encabezado, se podrá enviar el valor de los descuentos totales y de los impuestos totales que aplicarán a la compra.
Los campos dentro del encabezado serán: totDiscount y totTaxes
Detalle de los campos:
Elemento | Tipo de dato | Descripción | Requerido | Valor ante ausencia |
|---|---|---|---|---|
| totDiscount | Numérico | Importe total de descuento que calcula el POS. Será la sumatoria de descuentos que se apliquen a los artículos. | No | 0 |
| totTaxes | Numérico | Importe total de impuesto que calcula el POS. Será la sumatoria de impuestos que se apliquen sobre la compra. | No | 0 |
La manera de ejecutar un comando es utilizando una etiqueta con la forma <elemento-comando>. El elemento "item" identifica a los artículos. De esta manera, si se desea, por ejemplo, agregar un nuevo artículo el comando a utilizar será <item-add>. En el cuerpo del mensaje podrá contener uno, ninguno o varios de estos comandos.
...
| Aviso | ||
|---|---|---|
| ||
Esta estructura generada debe transformarse al formato Base 64 para informárselo a VTOL en el campo 270 posTicket. |
Estructura del campo paymentMethodsData (401)
El mensaje con la estructura de los medios de pago será en JSON. Estará conformado por los siguientes campos:
...
Código del Proveedor de la tarjeta configurado en VTOL. Por ejemplo para Visa el código es "VI".
El código se obtiene de la Configuración de POS.
...
Identificador del banco asociado a la tarjeta. Debe corresponder al ID de banco dispuesto por el BCRA.
Ver códigos de bancos.
...
Identificador de la opción de pago. Máximo 10 caracteres. Debe ser único dentro del campo "paymentMethodsData".
Permite trazabilidad con la opción que elija el cliente en el momento de pagar.
La opción de pago seleccionada por el cliente en su billetera virtual es retornada por VTOL en el mensaje de respuesta de la venta, en el campo 404.
...
Condición de la opción de pago. Sólo se informará si existe en VTOL una opción de pago con una condición.
Máximo 20 caracteres.
...
C.F.T. (Costo Financiero Total). Porcentaje de recargo sobre las cuotas. Valor entero. Los 2 últimos dígitos corresponden a los decimales.
...
T.N.A. (Tasa Nominal Anual). Valor entero. Los 2 últimos dígitos corresponden a los decimales.
...
Ejemplo del campo paymentMethodsData (401)
| Bloco de código |
|---|
| [ { "providerPosCode":"VIG", "bankCode":"7", "installments":[ { "paymentOptionId":"1", "quantity":"1", "amountPerInstallment":150000, "totalAmount":150000, "surcharge":0, "nominalAnnualRate":0, "defaultPosWalletInstallement":true }, { "paymentOptionId":"2", "quantity":"6", "amountPerInstallment":25000, "totalAmount":150000, "surcharge":1100, "nominalAnnualRate":1500 } ] }, { "providerPosCode":"VI", "installments":[ { "paymentOptionId":"3", "quantity":"12", "amountPerInstallment":15000, "totalAmount":180000, "surcharge":1256, "nominalAnnualRate":1487 } ] }, { "providerPosCode":"MC", "installments":[ { "paymentOptionId":"4", "quantity":"1", "amountPerInstallment":150000, "totalAmount":150000, "surcharge":0, "nominalAnnualRate":0 }, { "paymentOptionId":"5", "quantity":"12", "amountPerInstallment":15000, "totalAmount":180000, "surcharge":1256, "nominalAnnualRate":1487 } ] } ] |
1.4.26.2 Respuesta
| Informações | ||
|---|---|---|
| ||
X = Obligatorio |
...