|
1. Introducción
1.1. Propósito
Definir los procesos, y la mensajería para operar con PRISMA QR Grandes Cuentas.
2. Procesar mensaje PRISMA QR Grandes Cuentas
Para la definición de los campos y formato de mensaje aplicable a Transferencias 3.0, ver sección Mensajería – Request del manual PRISMA QR – Transferencias 3.0. |
Procesar la creación de la intención de compra (SaleWallet)
A continuación, se especifica el flujo del SaleWallet:
- El POS envía la transacción de venta (SaleWallet) a VTOL.
- VTOL se comunica con PRISMA QR para enviar la creación de la intención de compra al endpoint [POST] /largeaccounts/intentions.
- PRISMA QR responde con el mensaje HTTP 201 "Orden creada", en donde envía el campo intention_id que se refiere al identificador único de la intención creada. También envía el campo intention_type: "payment", entre otros.
- VTOL recibe el mensaje de que la orden fue creada correctamente y le informa al POS en los campos 27 isoCode: "542" y 28 responseMessage: "Esperando medios de pago del autorizador" para informar que se debe esperar que PRISMA envíe los bines. Luego se envía una queryWallet del POS a VTOL para consultar por los bines.
- El usuario escanea el QR desde la billetera electrónica y se envía la consulta de la intención de compra a PRISMA QR. La billetera agrega los bines en la intención de compra mediante el método PUT, luego PRISMA recibe la información y responde ok. Nota: los bines que se agregan en la intención de compra corresponden solo a los bines de las tarjetas que tiene el usuario registrado en la billetera.
- Recibir bines de Prisma (corresponde a las tarjetas que tiene el usuario en su billetera electrónica)
Luego de la creación del SaleWallet, VTOL deberá recibir los bines de PRISMA. A continuación, se especifica el flujo:
- PRISMA QR le envía a VTOL los bines mediante el endpoint [PUT] /{integrator_path}/intentions/{intention_id}.
- VTOL le responde a PRISMA con el código HTTP 204 "Intención recibida correctamente". Luego VTOL deberá relacionar los bines recibidos con los Providers que están configurados en VTOL (prefijos) y que se encuentran en la base de datos.
- El POS envía una QueryWallet genérica para consultar por los medios de pago de la billetera. VTOL responde (isoCode: 543 y responseMessage: "Enviar medios de pago)" con la información de los Providers que tiene el cliente en su billetera, en el campo 401 walletPaymentMethod y si existen tarjetas de beneficios, se enviará en el campo 402 walletBenefit.
- El POS calcula las promociones según la información de los Providers recibida desde VTOL en el campo 401.
- Enviar las cuotas de los Providers en la intención de compra completa (QueryWallet)
A continuación, se especifica el flujo para enviar la intención de compra completa con los Providers:
- El POS le envía a VTOL la intención de compra completa (en un QueryWallet) con los Providers en el campo 401 "walletPaymentMethod", es decir, le envía los planes de pago que el usuario podrá elegir desde la billetera. Importante: En este requerimiento de QueryWallet el POS debe agregar obligatoriamente la opción de pago "TR" Transferencia dentro del campo 401, ya que es un dato que espera recibir siempre Payway. Con esta QueryWallet se debe envía el mensaje a Payway para completar la intención de compra.
- VTOL envía a PRISMA QR la intención de compra completa con los medios de pago al endpoint [PUT] /largeaccounts/intentions/complete?cuit={value}&branch={value}&checkout={value}
- PRISMA responde a VTOL con el código HTTP 204 "Intención recibida correctamente" y le envía a la billetera la información de las opciones de pago según las tarjetas que tiene el usuario en su billetera.
- El usuario visualizará el detalle de la compra con las opciones de pago disponibles enviadas por la caja y efectuará el pago seleccionando la tarjeta y las cuotas, de esta forma se confirma el pago.
- PRISMA autoriza la compra.
- VTOL consulta el estado de la compra mediante el endpoint [GET] /payments/qr?intention_id={value} y recibe la respuesta de PRISMA QR. Se pueden presentar los siguientes escenarios:
- Si el pago se realizó correctamente, entonces PRISMA le envía a VTOL la respuesta del estado de la orden "Approved", entonces se incrementa el ticket y trace de la caja en la cual se realizó la operación. Por lo tanto, VTOL actualiza el estado de la orden en la tabla WalletFinancial y le responde al POS con el estado de la transacción aprobada (isoCode "00" y responseMessage "Aprobada"). El paso siguiente del POS es confirmar o cancelar la transacción, con un tercer mensaje.
- Si se presenta algún problema para efectuar el pago y VTOL no recibe de PRISMA la respuesta/notificación del pago, entonces desde el POS se consulta por el pago.
- Fin del flujo.
Diagrama de secuencia
A continuación, se especifica el diagrama que contiene los tres flujos definidos anteriormente:
- Procesar la creación de la intención de compra (SaleWallet)
- Recibir bines de Prisma (corresponde a las tarjetas que tiene el usuario en su billetera)
- Enviar los Providers en la intención de compra completa (QueryWallet)
Mensajería POS - VTOL - Transacción "SaleWallet" (Crear intención de pago)
A continuación, se especifica la mensajería de la operación SaleWallet, en donde se envía la creación de la intención de compra.
- Request POS - VTOL
X = Obligatorio |
Número | Nombre del campo | Tipo de dato | SaleWallet | Descripción |
|---|---|---|---|---|
| 0 | company | Numérico | M | Identificador de la compañía donde se generó la transacción. Exclusivo para mensajería POS-VTOL. |
| 1 | store | Alfanumérico | M | Identificador del local donde se generó la transacción. Exclusivo para mensajería POS-VTOL. |
| 2 | node | Numérico | M | Identificador de la caja donde se generó la transacción. Exclusivo para mensajería POS-VTOL. |
| 3 | server | Alfanumérico | M | Identificador del Server que procesará la transacción, en el caso de VTOL será "VTOL". Exclusivo para mensajería POS-VTOL. |
| 4 | messageType | Alfanumérico | M | Indica el tipo de mensaje:
Exclusivo para mensajería POS-VTOL. |
| 11 | trxType | Alfanumérico | M | Indica el tipo de transacción:
|
| 12 | amount | Numérico | M | Monto de la transacción. 12 dígitos como máximo. Se envía sin coma. Los dos últimos dígitos representan los decimales. Ejemplo: "1000" equivale a "10.00". |
| 13 | currencyPosCode | Alfanumérico | M | Tipos de moneda: $ = Pesos |
| 24 | lastTrxId | Numérico | O | En este campo el POS debe enviar la última transacción procesada correctamente. Se utiliza si está activo el control transaccional. |
| 25 | dateTime | Numérico | M | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
| 268 | walletPosTrxId | Alfanumérico | M | 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 QuerySaleWallet: Se informa este campo o el campo walletPaymentId para localizar una transacción de compra. |
| 269 | walletType | Numérico | M | Tipo de billetera por la cual se realizará la transacción en el POS. La opción corresponde a 3: MODO. |
| 270 | walletPosTicket | Alfanumérico | M | Información del ticket en formato xml y posteriormente transformado en Base 64. |
| 401 | walletPaymentMethod | Formato Json codificado en Base 64 | O | Información de los planes de pago. La estructura de este campo está definida en la siguiente sección del documento. Importante: en este MENSAJE sólo se envía el valor "TR" que corresponde a pago con transferencia 3.0. Se envía solo si el comercio opera con Transferencia 3.0 sino no se envía. |
Estructura del campo 401 (walletPaymentMethod):
X = Obligatorio |
| Parámetro | Tipo de dato | Referencia | Descripción | |
|---|---|---|---|---|
| providerPosCode | Alfanumérico | M | Código del Proveedor de la tarjeta configurado en VTOL. En este MENSAJE sólo se envía el valor "TR" que corresponde a pago con transferencia 3.0. Se envía solo si el comercio opera con Transferencia 3.0 Nota: para Transferencias 3.0 corresponde a "TR". | |
| bankCode | Numérico | O | Identificador del banco asociado a la tarjeta. Debe corresponder al ID de banco dispuesto por el BCRA. Nota: para Transferencias 3.0 no se envía este campo. | |
| installments | Array | M | Información de las cuotas. | |
paymentOptionId | Alfanumérico | M | Identificador de la opción de pago creada por el POS. Máximo 10 caracteres. Debe ser único dentro del campo "paymentMethodsData". Permite trazabilidad con la opción elegida por 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. | |
| quantity | Numérico | M | Cantidad de cuotas. Máximo 2 dígitos. Nota: para transferencias 3.0 (pago con saldo en cuenta) es una cuota, por lo cual, el valor del campo es 1. | |
| paymentCondition | Alfanumérico | O | Condición de la opción de pago. Sólo se informará si existe configurada en VTOL una opción de pago con una condición. Máximo 20 caracteres. | |
| amountPerInstallment | Importe | M | Monto por cuotas. Valor entero. Los 2 últimos dígitos corresponden a los decimales. Nota: para transferencias 3.0 el valor de este campo deberá ser igual al totalAmount. | |
| totalAmount | Importe | M | Monto total. Incluye los recargos. Valor entero. Los 2 últimos dígitos corresponden a los decimales. Nota: para transferencias 3.0 el valor de este campo deberá ser igual al amountPerInstallment. | |
| surcharge | Decimal | M | Porcentaje de recargo sobre las cuotas. Valor entero. Los 2 últimos dígitos corresponden a los decimales.
Nota: para transferencias 3.0 el valor de este campo es 0, ya que no existe recargo. | |
| nominalAnnualRate | Decimal | M | Tasa Nominal Anual. Valor entero. Los 2 últimos dígitos corresponden a los decimales.
| |
Ejemplo:
Request SaleWallet (log emvkit):
Request: {270:PG1lc3NhZ2UgY29tcGFueUlkPSJzdHMiIHN0b3JlPSIwMDAwMSIgdGVybWluYWw9IjAxMCIgZGF0 |
Para los valores de respuesta y comportamiento específicos de Transferencias 3.0, consultar sección Mensajería – Response del manual PRISMA QR – Transferencias 3.0 |
- Response VTOL - POS
Número | Nombre del campo | Tipo de dato | SaleWallet | Descripción |
|---|---|---|---|---|
| 0 | company | Numérico | M | Identificador de la compañía donde se generó la transacción |
| 1 | store | Alfanumérico | M | Identificador del sitio originador de la transacción |
| 2 | node | Numérico | M | Identificación del nodo, en el sitio originador, donde se generó la transacción. |
| 12 | amount | Importe | M | Contiene el Importe que pagó el cliente, el cual puede variar si pagó con intereses o se aplicó algún descuento. Valor entero. Los últimos 2 dígitos corresponden a los decimales. |
| 13 | currencyPosCode | Alfanumérico | M | Tipos de moneda: $ = Pesos |
| 14 | payments | Numérico | M | Cantidad de cuotas seleccionada al momento de realizar el pago QR. Nota: este campo deberá tener el valor 1 si el pago se realiza con transferencia 3.0 (pago con saldo en cuota). Si el pago se realiza con tarjeta puede tomar otro valor. |
| 22 | authorizationCode | Alfanumérico | O | Código de autorización informado por el Autorizador |
| 24 | trxId | Numérico | M | Identificador de la transacción. |
25 | dateTime | Numérico | M | 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 | M | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | M | Código de Respuesta emitido por el centro autorizador. 2 dígitos como máximo. Ver sección Códigos de Respuesta de VTOL Server para Billeteras Electrónicas Nota: Se envía en este campo el código 542. |
28 | responseMessage | Alfanumérico | M | Mensaje de la respuesta relacionado con el código del campo 27. Nota: Se envía en este campo el mensaje "Esperando medios de pago del autorizador" que corresponde al código 542 enviado en el campo 27 de la mensajería de VTOL al POS |
29 | serialNumber | Numérico | O | Número identificatorio de la terminal en la que se procesó la transacción. Retorna en operaciones aprobadas. |
31 | lotNumber | Numérico | O | Número de lote en el que se registró la transacción |
32 | ticket | Numérico | O | Número de Ticket correspondiente a la transacción. 4 dígitos como máximo. |
| 54 | additionalAmount | Importe | O | Contiene el Importe del "Cashout". Aplica para las operaciones realizadas con retiro de efectivo. Valor entero. Los últimos 2 dígitos corresponden a los decimales. |
140 | paymentType | Numérico | M | Tipo de pago. Valores posibles: 0: Tarjeta |
| 157 | customerDoc | Numérico | O | Numero de documento del titular de la tarjeta. |
| 166 | trxReferenceNumber | Numérico | M | 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 | M | Identificador del número de pago informado por el Autorizador |
| 272 | amountRefunded | Importe | - | Monto devuelto en la transacción |
| 273 | paymentStatus | Alfanumérico | O | Estado de la transacción de pago informado por el Autorizador. Estados posibles: 0: Aprobado |
| 274 | paymentStatusDetail | Alfanumérico | 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. Valores posibles: 0: Débito |
| 404 | paymentOptionId | Alfanumérico | O | Identificador de la opción de pago seleccionada por el cliente en su billetera virtual. Según la tarjeta, el banco, y las cuotas elegidas por el cliente, se identificará con el paymentOptionId enviado por la caja. |
| 405 | benefitCardId | Alfanumérico | O | Identificador de la tarjeta de beneficio aplicada en el pago por estar vinculada en la billetera virtual del cliente. |
| 406 | originalAmount | Importe | O | Monto original de la transacción: de venta o de devolución. |
| 407 | amountDiscounted | Importe | O | Contiene el importe que se descontó sobre el importe original. Debido a la aplicación de una tarjeta de beneficio vinculada en la billetera virtual del cliente. Sólo retorna cuando se aplicó un descuento. |
| 428 | TID | Alfanumérico (long. 15) | ID de transacción de la marca para pagos ydevoluciones aprobadas de los siguientes medios de pago: | |
| 1010 | currentSessionId | Numérico | M | Identificador de la sesión |
| 1027 | libResponseCode | Numérico | M | Código de respuesta de la librería. Indica cómo fue procesada la operación en EMVKIT: Éxito = 000 |
| 1028 | libResponseMessage | Alfanumérico | M | Mensaje descriptivo del código de respuesta de la librería |
Ejemplo:
Response message: {32:0;1:15;2:70486;1027:000;1028:Ok;421:17447444605040;166:15042516142000127841;140:0;12:00;13:$;14:0;272:00;273:4;1010:1744744445373;275:0;24:10;25:20250415161408;26:ISO8583;27:542;28:Esperando medios de pagos del autorizador;31:1} |
Mensajería POS - VTOL - Transacción "QueryWallet" (Recibir bines de Prisma)
A continuación, se define la mensajería para procesar los bines de PRISMA (tarjetas que tiene el cliente en su billetera).
El POS envía a VTOL una QueryWallet genérica para consultar por los medios de pago.
- Request POS - VTOL:
X = Obligatorio |
Número | Nombre del campo | Tipo de dato | QueryWallet | Descripción |
|---|---|---|---|---|
| 0 | company | Numérico | M | Identificador de la compañía donde se generó la transacción |
| 1 | store | Alfanumérico | M | Identificador del sitio originador de la transacción |
| 2 | node | Numérico | M | Identificación del nodo, en el sitio originador, donde se generó la transacción. |
| 3 | server | Alfanumérico | M | Identificador del Server que procesará la transacción, en el caso de VTOL será "VTOL". Exclusivo para mensajería POS-VTOL. |
| 4 | messageType | Alfanumérico | M | Indica el tipo de mensaje:
Exclusivo para mensajería POS-VTOL. |
| 11 | trxType | Alfanumérico | M | Indica el tipo de transacción:
|
| 16 | originalDate | Numérico | M | Fecha de realización de la compra con billetera electrónica en formato YYYYMMDD |
| 25 | dateTime | Numérico | M | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
| 71 | checkPendingString | Alfanumérico | O | Indica si VTOL debe o no efectuar el chequeo de pendientes (se emplea para pagos parciales de tarjetas):
|
| 268 | walletPosTrxId | Alfanumérico | M | 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 QuerySaleWallet: Se informa este campo o el campo walletPaymentId para localizar una transacción de compra. |
| 269 | walletType | Numérico | M | Tipo de billetera por la cual se realizará la transacción en el POS. La opción corresponde a 3: MODO. |
Ejemplo:
Request QueryWallet (log emvkit):
{269:3;16:20250415;268:0000000015000007048620251415041408;14:0;12:140000;11:QueryWallet;6:4905;2:70486;25:20250415161432;24:10;1:15} |
- Response VTOL - POS
VTOL responde (isoCode 543 y responseMessage "Enviar medios de pago") con la información de los Providers en el campo 401 "walletPaymentMethod".
Importante: Puede darse el caso que el cliente pagó con TRANSFERENCIA y por lo tanto la respuesta de este QueryWallet retorne con el pago APROBADO, sin necesitar enviar los planes de pago.
Número | Nombre del campo | Tipo de dato | QueryWallet | Descripción |
|---|---|---|---|---|
| 0 | company | Numérico | M | Identificador de la compañía donde se generó la transacción |
| 1 | store | Alfanumérico | M | Identificador del sitio originador de la transacción |
| 2 | node | Numérico | M | Identificación del nodo, en el sitio originador, donde se generó la transacción. |
| 12 | amount | Importe | M | Contiene el Importe que pagó el cliente, el cual puede variar si pagó con intereses o se aplicó algún descuento. Valor entero. Los últimos 2 dígitos corresponden a los decimales. |
| 13 | currencyPosCode | Alfanumérico | M | Tipos de moneda: $ = Pesos |
| 14 | payments | Numérico | M | Cantidad de cuotas seleccionada al momento de realizar el pago QR. Nota: este campo deberá tener el valor 1 si el pago se realiza con transferencia 3.0 (pago con saldo en cuota). Si el pago se realiza con tarjeta puede tomar otro valor. |
| 24 | trxId | Numérico | M | Identificador de la transacción. |
25 | dateTime | Numérico | M | 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 | M | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | M | Código de Respuesta emitido por el centro autorizador. 2 dígitos como máximo. Ver sección Códigos de Respuesta de VTOL Server para Billeteras Electrónicas |
28 | responseMessage | Alfanumérico | M | Mensaje de la respuesta relacionado con el código del campo 27 |
32 | ticket | Numérico | O | Número de Ticket correspondiente a la transacción. 4 dígitos como máximo. |
| 140 | paymentType | Numérico | M | Tipo de pago. Valores posibles: 0: Tarjeta |
| 166 | trxReferenceNumber | Numérico | M | 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 | M | Identificador del número de pago informado por el Autorizador |
| 272 | amountRefunded | Importe | M | Monto devuelto en la transacción |
| 273 | paymentStatus | Alfanumérico | O | Estado de la transacción de pago informado por el Autorizador. Estados posibles: 0: Aprobado |
| 274 | paymentStatusDetail | Alfanumérico | 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. El campo es opcional en caso de que se haya abonado con saldo de la cuenta de Mercado Pago. Valores posibles: 0: Débito |
| 401 | walletPaymentMethod | Formato Json codificado en Base 64 | O | Información de los bines de la tarjeta que tiene el cliente en su app bancaria. Ver ejemplo de la respuesta más abajo. El valor del campo se encuentra codificado en Base 64. |
| 402 | walletBenefit | Formato Json | O | Información de las tarjetas de beneficio aceptadas. |
| 404 | paymentOptionId | Alfanumérico | O | Identificador de la opción de pago seleccionada por el cliente en su billetera virtual. Según la tarjeta, el banco, y las cuotas elegidas por el cliente, se identificará con el paymentOptionId enviado por la caja. |
| 405 | benefitCardId | Alfanumérico | O | Identificador de la tarjeta de beneficio aplicada en el pago por estar vinculada en la billetera virtual del cliente. |
| 406 | originalAmount | Importe | M | Monto original de la transacción: de venta o de devolución. |
| 407 | amountDiscounted | Importe | O | Contiene el importe que se descontó sobre el importe original. Debido a la aplicación de una tarjeta de beneficio vinculada en la billetera virtual del cliente. Sólo retorna cuando se aplicó un descuento. |
| 1010 | currentSessionId | Numérico | M | Identificador de la sesión |
| 1027 | libResponseCode | Numérico | M | Código de respuesta de la librería. Indica cómo fue procesada la operación en EMVKIT: Éxito = 000 |
| 1028 | libResponseMessage | Alfanumérico | M | Mensaje descriptivo del código de respuesta de la librería |
Campo 401 en la respuesta informando la tarjeta que seleccionó el cliente en su app bancaria
EMVKIT responde al POS ese campo codificado en Base 64. Al decodificarlo a texto se encuentra un Json con la siguiente estructura:
| [{"posCode":"VIG","bank_id":7,"bin":459354},{"posCode":"VI","bank_id":44,"bin":430496},{"posCode":"MC","bank_id":20,"bin":529991}] |
Estructura del campo 401 (walletPaymentMethod):
| Parámetro | Tipo de dato | Descripción | |
|---|---|---|---|
| providerCode | Alfanumérico | Código del Proveedor de la tarjeta configurado en VTOL. Por ejemplo: VI (Visa), MC (mastercard), MA (Maestro), entre otros. | |
| bank_id | Numérico | Identificador del banco asociado a la tarjeta. Debe corresponder al ID de banco dispuesto por el BCRA. | |
| bin | Numérico | BIN de la tarjeta que tiene el cliente en su billetera electrónica. | |
Ejemplo Response QueryWallet (log emvkit):
Response message:
{32:0;1:15;2:70486;1027:000;1028:Ok;421:17447444605040;140:0;12:140000;13:$;14:0;272:00;273:4;401:W3sicG9zQ29kZSI6IkFNUyIsImJhbmtfaWQiOjcyLCJiaW4iOjM3MTU5NX1d;402:W10=;1010:1744744445373;275:0;406:140000;24:10;25:20250415161432;26:ISO8583;27:543;28:Enviar medios de pagos;31:1} |
Ejemplo Response con pago Aprobado con TRANSFERENCIA 3.0
Response message: {1:1111;2:4;1027:000;1028:Ok;140:1;12:140000;13:$;14:1;142:Transferencias 3.0;271:3690197251017;15:0;272:00;273:0;274:approved;275:0;147:TR;406:140000;22:IHDHPQ;24:168;25:20251017174429;26:ISO8583;27:00;28:APROBADA;30:11111111;31:33;32:1121;421:3002362;422:171802845;306:0;1010:1760733833997}
Request: {1009:{168};1008:CLOSE;25:20251017174438;2:4;1:1111;11:closeSession}
Response message: {1010:1760733833997;1027:000;1028:Ok} |
Mensajería POS - VTOL - Transacción "QueryWallet" (Intención de compra completa)
A continuación, se especifica la mensajería del envío desde el POS de los Providers y Cuotas en la intención de compra completa mediante la operación QueryWallet
- Request POS - VTOL:
Número | Nombre del campo | Tipo de dato | QueryWallet | Descripción |
|---|---|---|---|---|
| 0 | company | Numérico | M | Identificador de la compañía donde se generó la transacción. Exclusivo para mensajería POS-VTOL. |
| 1 | store | Alfanumérico | M | Identificador del local donde se generó la transacción. Exclusivo para mensajería POS-VTOL. |
| 2 | node | Numérico | M | Identificador de la caja donde se generó la transacción. Exclusivo para mensajería POS-VTOL. |
| 3 | server | Alfanumérico | M | Identificador del Server que procesará la transacción, en el caso de VTOL será "VTOL". Exclusivo para mensajería POS-VTOL. |
| 4 | messageType | Alfanumérico | M | Indica el tipo de mensaje:
Exclusivo para mensajería POS-VTOL. |
| 11 | trxType | Alfanumérico | M | Indica el tipo de transacción:
|
| 12 | amount | Numérico | O | Monto de la transacción. 12 dígitos como máximo. Se envía sin coma. Los dos últimos dígitos representan los decimales. Ejemplo: "1000" equivale a "10.00". |
| 13 | currencyPosCode | Alfanumérico | O | Tipos de moneda: $ = Pesos |
| 16 | originalDate | Numérico | M | Fecha de realización de la compra con billetera electrónica en formato YYYYMMDD |
| 24 | lastTrxId | Numérico | O | En este campo el POS debe enviar la última transacción procesada correctamente. Se utiliza si está activo el control transaccional. |
| 25 | dateTime | Numérico | M | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
| 71 | checkPendingString | Alfanumérico | O | Indica si VTOL debe o no efectuar el chequeo de pendientes (se emplea para pagos parciales de tarjetas):
|
| 268 | walletPosTrxId | Alfanumérico | M | 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 QuerySaleWallet: Se informa este campo o el campo walletPaymentId para localizar una transacción de compra. |
| 269 | walletType | Numérico | M | Tipo de billetera por la cual se realizará la transacción en el POS. La opción corresponde a 3: MODO. |
| 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 QuerySaleWallet: Se informa este campo o el campo walletPosTrxId para localizar una transacción de compra. |
| 401 | walletPaymentMethod | Formato Json codificado en Base 64 | M | Información de los planes de pago. La estructura de este campo está definida en la siguiente sección del documento. Importante: en este MENSAJE se debe agregar obligatoriamente el valor "TR" que corresponde a pago con transferencia 3.0. |
| 402 | walletBenefit | Formato Json | O | Información de las tarjetas de beneficio aceptadas. |
Estructura del campo 401 (walletPaymentMethod):
Referencia de campos:
M = Mandatorio.
O = Opcional.
| Parámetro | Tipo de dato | Referencia | Descripción | |
|---|---|---|---|---|
| providerPosCode | Alfanumérico | M | Código del Proveedor de la tarjeta configurado en VTOL. Por ejemplo: VI (Visa), MC (mastercard), MA (Maestro), entre otros. | |
| bankCode | Numérico | O | Identificador del banco asociado a la tarjeta. Debe corresponder al ID de banco dispuesto por el BCRA. Nota: para Transferencias 3.0 no se envía este campo. | |
| installments | Array | M | Información de las cuotas. | |
paymentOptionId | Alfanumérico | M | Identificador de la opción de pago creada por el POS. Máximo 10 caracteres. Debe ser único dentro del campo "paymentMethodsData". Permite trazabilidad con la opción elegida por 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. | |
| quantity | Numérico | M | Cantidad de cuotas. Máximo 2 dígitos. Nota: para transferencias 3.0 (pago con saldo en cuenta) es una cuota, por lo cual, el valor del campo es 1. | |
| paymentCondition | Alfanumérico | O | Condición de la opción de pago. Sólo se informará si existe configurada en VTOL una opción de pago con una condición. Máximo 20 caracteres. | |
| amountPerInstallment | Importe | M | Monto por cuotas. Valor entero. Los 2 últimos dígitos corresponden a los decimales. Nota: para transferencias 3.0 el valor de este campo deberá ser igual al totalAmount. | |
| totalAmount | Importe | M | Monto total. Incluye los recargos. Valor entero. Los 2 últimos dígitos corresponden a los decimales. Nota: para transferencias 3.0 el valor de este campo deberá ser igual al amountPerInstallment. | |
surcharge (cft) | Decimal | M | Porcentaje de recargo sobre las cuotas. Valor entero. Los 2 últimos dígitos corresponden a los decimales.
Nota: para transferencias 3.0 el valor de este campo es 0, ya que no existe recargo. | |
nominalAnnualRate (tna) | Decimal | M | Tasa Nominal Anual. Valor entero. Los 2 últimos dígitos corresponden a los decimales.
| |
Estructura del campo walletBenefit (402)
Se agrega el nuevo campo “card_number” en el objeto “benefits_methods_data” del request de Reenviar bines al integrador. El mensaje con la estructura de los beneficios estará en formato JSON codificado en Base 64 conformada por los siguientes campos:
| Parámetro | Tipo de dato | Requerido | Descripción | |
|---|---|---|---|---|
benefitCardId | Alfanumérico | Si | Identificador de la opción de pago creada por el POS. Máximo 10 caracteres. Debe ser único dentro del campo "walletBenefits". Permite trazabilidad con la tarjeta de beneficio aplicada en el pago por estar vinculada en la billetera virtual del cliente. El ID del beneficio aplicado es retornado por VTOL en el mensaje de respuesta de la venta en el campo 405. | |
| providerPosCode | Alfanumérico | Si | Código de la tarjeta de beneficio configurada en VTOL. Por ejemplo, para Clarin 365 el código es "CC". | |
| card_number | Numérico | SI (solo si se envía el campo benefits_methods_data.bene fits_card.code) | Número de la tarjeta de beneficios. Importante: el campo “card_number” se agregó en el objeto “benefits_methods_data” del request de "Reenviar bines al integrador", por lo cual se envía en este request. | |
discountPercentage | Numérico | Si | Porcentaje de descuento a aplicar sobre la compra. Valor entero. Los 2 últimos dígitos corresponden a los decimales. | |
maximumDiscountAmount | Numérico | Si | Importe máximo de descuento a aplicar sobre la compra. Valor entero. Los 2 últimos dígitos corresponden a los decimales. | |
Ejemplo Request QueryWallet (log emvkit):
Request: {269:3;16:20250415;268:0000000015000007048620251415041408;12:140000;11:QueryWallet;401:[ |
- Response VTOL - POS:
Número | Nombre del campo | Tipo de dato | QueryWallet | Descripción |
|---|---|---|---|---|
| 0 | company | Numérico | M | Identificador de la compañía donde se generó la transacción |
| 1 | store | Alfanumérico | M | Identificador del sitio originador de la transacción |
| 2 | node | Numérico | M | Identificación del nodo, en el sitio originador, donde se generó la transacción. |
| 6 | cardNumber | Alfanumérico | O | Tarjeta enmascarada seleccionada por el cliente al momento de efectuar el pago QR. Importante: este campo no se envía si el pago se realiza con Transferencias 3.0, pero en caso de pagos con tarjetas si es obligatorio. |
| 12 | amount | Importe | M | Contiene el Importe que pagó el cliente, el cual puede variar si pagó con intereses o se aplicó algún descuento. Valor entero. Los últimos 2 dígitos corresponden a los decimales. |
| 13 | currencyPosCode | Alfanumérico | M | Tipos de moneda: $ = Pesos |
| 14 | payments | Numérico | M | Cantidad de cuotas seleccionada al momento de realizar el pago QR. Importante: este campo deberá tener el valor 1 si el pago se realiza con transferencia 3.0 (pago con saldo en cuota). Si el pago se realiza con tarjeta puede tomar otro valor. |
15 | plan | Numérico | M | Plan de pago. Campo de 1 carácter de longitud. Nota: si el pago se realiza por Transferencias, el campo toma el valor de 0. |
| 22 | authorizationCode | Alfanumérico | M | Código de autorización informado por el Autorizador |
| 24 | trxId | Numérico | M | Identificador de la transacción. |
| 25 | dateTime | Numérico | M | 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 | M | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | M | Código de Respuesta emitido por el centro autorizador. 2 dígitos como máximo. Ver sección Códigos de Respuesta de VTOL Server para Billeteras Electrónicas |
28 | responseMessage | Alfanumérico | M | Mensaje de la respuesta relacionado con el código del campo 27 |
29 | serialNumber | Numérico | O | Número identificatorio de la terminal en la que se procesó la transacción. Retorna en operaciones aprobadas. |
30 | bussinesNumber | Numérico | M | Número de comercio en el que se procesó la transacción. |
31 | lotNumber | Numérico | O | Número de lote en el que se registró la transacción |
32 | ticket | Numérico | O | Número de Ticket correspondiente a la transacción. 4 dígitos como máximo. |
| 81 | responseAuth | Alfanumérico | O | Mensaje de repuesta para imprimir en el ticket del POS. Retorna en operaciones aprobadas. Contiene información generada por el Autorizador. |
| 140 | paymentType | Numérico | - | Tipo de pago. Valores posibles: 0: Tarjeta |
| 142 | providerName | Alfanumérico | - | Proveedor de la tarjeta seleccionada al momento de efectuar el pago QR. |
| 147 | providerPosCode | Alfanumérico | O | Código del Provider. Retornará cuando la transacción fue aprobada por el Autorizador. Nota: si el pago se realiza con Transferencias 3.0 el código es "TR" |
| 157 | customerDoc | Numérico | O | Numero de documento del titular de la tarjeta. |
| 303 | customerName | Alfanumérico | O | Nombre del titular de la tarjeta. |
271 | walletPaymentId | Alfanumérico | M | Identificador del número de pago informado por el Autorizador |
| 272 | amountRefunded | Importe | - | Monto devuelto en la transacción |
| 273 | paymentStatus | Alfanumérico | O | Estado de la transacción de pago informado por el Autorizador. Estados posibles: 0: Aprobado |
| 274 | paymentStatusDetail | Alfanumérico | O | Detalle del estado de la transacción de pago informado por el Autorizador |
| 275 | cardType | Numérico | - | Tipo de 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. Valores posibles: 0: Débito |
| 306 | cardIssuingBank | Alfanumérico | O | Banco emisor de la tarjeta. Retornará cuando la transacción fue aprobada por el Autorizador. |
| 404 | paymentOptionId | Alfanumérico | M | Identificador de la opción de pago seleccionada por el cliente en su billetera virtual. Según la tarjeta, el banco, y las cuotas elegidas por el cliente, se identificará con el paymentOptionId enviado por la caja. |
| 405 | benefitCardId | Alfanumérico | O | Identificador de la tarjeta de beneficio aplicada en el pago por estar vinculada en la billetera virtual del cliente. |
| 406 | originalAmount | Importe | M | Monto original de la transacción: de venta o de devolución. |
| 407 | amountDiscounted | Importe | O | Contiene el importe que se descontó sobre el importe original. Debido a la aplicación de una tarjeta de beneficio vinculada en la billetera virtual del cliente. Sólo retorna cuando se aplicó un descuento. |
| 421 | walletOrderId | Alfanumérico | O | Campo que retorna desde Payway asociado al intention_id. |
| 422 | walletTransactionId | Alfanumérico | O | Campo que retorna desde Payway asociado al transaction_id. |
| 1010 | currentSessionId | Numérico | M | Identificador de la sesión |
| 1027 | libResponseCode | Numérico | M | Código de respuesta de la librería. Indica cómo fue procesada la operación en EMVKIT: Éxito = 000 |
| 1028 | libResponseMessage | Alfanumérico | M | Mensaje descriptivo del código de respuesta de la librería |
Ejemplo Response QueryWallet (log emvkit):
Response message: {1:15;2:70486;1027:000;1028:Ok;6:450799...4851;140:0;12:140000;13:$;14:1;142:Visa;271:16151206;272:00;273:0;81:COMPRA QR;274:approved;275:1;406:140000;22:184603;407:1000;24:10;25:20250415161508;26:ISO8583;27:00;28:APROBADA;31:1;32:2;421:17447444605040;306:1;1010:1744744445373} |
Flujo de la Devolución forzada (RefundWallet)
- El POS le envía a VTOL la operación “RefundWallet” con los campos 271 walletPaymentId, 24 trxId (opcional) y el 12 Ammount. Nota: solo se permiten las devoluciones por el monto total de la compra, no se permiten devoluciones parciales.
- VTOL se comunica con PRISMA mediante el endpoint GET integrations/payments/qr?intention_id para consultar el estado de la orden, en donde se envía el parámetro intention_id que identifica el id de la intención de compra que se desea devolver.
- PRISMA responde el código HTTP 200 con el estado de la transacción de compra y los datos de la operación. Importante: la orden debe estar confirmada (status: approved) para poder realizar la devolución.
- VTOL le responde al POS con el estado de la orden confirmada, con el campo 27 isoCode = 00 y el campo 28 responseMessage = Aprobada.
- El POS le envía a VTOL el tercer mensaje "Commit".
- VTOL se comunica con PRISMA mediante el endpoint [POST] /forcedrefunds, en donde envía el parámetro "intention_id", entre otros, para enviar la intención de devolución.
- PRISMA le responde a VTOL con los datos de la transacción y el "status: refund_in_progress". Luego entre PRISMA y la billetera se comunican para solicitar el pedido de datos. PRISMA procesa la devolución y envía la notificación de la devolución forzada a la billetera.
- VTOL le consulta a PRISMA el estado de la compra mediante el endpoint [GET] /payments/qr?intention_id={value} y PRISMA responde los datos de la operación junto con el status: "refunded".
- PRISMA le envía a VTOL la notificación de la devolución forzada. Ver proceso "Recibir notificación de devolución forzada" por parte de VTOL
Diagrama de secuencia de la devolución forzada (RefundWallet)
A continuación, se especifica la mensajería:
Para más información sobre el flujo de devoluciones con Transferencias 3.0, consultar el manual PRISMA QR – Transferencias 3.0 |
Mensajería POS - VTOL - Transacción "RefundWallet" (Devolución forzada)
- Request POS - VTOL:
Número | Nombre del campo | Tipo de dato | RefundWallet | Descripción |
|---|---|---|---|---|
| 0 | company | Numérico | M | Identificador de la compañía donde se generó la transacción. Exclusivo para mensajería POS-VTOL. |
| 1 | store | Alfanumérico | M | Identificador del local donde se generó la transacción. Exclusivo para mensajería POS-VTOL. |
| 2 | node | Numérico | M | Identificador de la caja donde se generó la transacción. Exclusivo para mensajería POS-VTOL. |
| 3 | server | Alfanumérico | M | Identificador del Server que procesará la transacción, en el caso de VTOL será 'VTOL'. Exclusivo para mensajería POS-VTOL. |
| 4 | messageType | Alfanumérico | M | Indica el tipo de Mensaje:
Exclusivo para mensajería POS-VTOL. |
| 11 | trxType | Alfanumérico | M | Tipo de Transacción:
|
| 12 | amount | Numérico | M | Monto de la transacción. 12 dígitos como máximo. Se envía sin coma. Los dos últimos dígitos representan los decimales. Ej: "1000" equivale a "10.00". |
| 13 | currencyPosCode | Alfanumérico | M | Indica el tipo de moneda: $ = Pesos |
| 16 | originalDate | Numérico | M | Fecha de realización de la compra con billetera electrónica en formato YYYYMMDD |
| 24 | lastTrxId | Numérico | O | En este campo el POS debe enviar la última transacción procesada correctamente. Se utiliza si está activo el control transaccional. |
| 25 | dateTime | Numérico | M | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
| 268 | walletPosTrxId | Alfanumérico | M | 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 QuerySaleWallet: Se informa este campo o el campo walletPaymentId para localizar una transacción de compra. |
| 269 | walletType | Numérico | M | Tipo de billetera por la cual se cursará la transacción en el POS. La opción corresponde a 3: MODO. |
| 271 | walletPaymentId | Alfanumérico | M | Identificador del número de pago informado por el Autorizador en el campo 271 de la respuesta de la operación SaleWallet. Opcional en QuerySaleWallet: Se informa este campo o el campo walletPosTrxId para localizar una transacción de compra. |
- Response VTOL - POS:
Número | Nombre del campo | Tipo de dato | RefundWallet | Descripción |
|---|---|---|---|---|
| 0 | company | Numérico | M | Identificador de la compañía donde se generó la transacción |
| 1 | store | Alfanumérico | M | Identificador del sitio originador de la transacción |
| 2 | node | Numérico | M | Identificación del nodo, en el sitio originador, donde se generó la transacción. |
| 6 | cardNumber | Alfanumérico | - | Tarjeta enmascarada seleccionada por el cliente al momento de efectuar el pago QR. |
| 12 | amount | Importe | - | Contiene el Importe que pagó el cliente, el cual puede variar si pagó con intereses o se aplicó algún descuento. Valor entero. Los últimos 2 dígitos corresponden a los decimales. |
| 13 | currencyPosCode | Alfanumérico | - | Tipo de moneda: $ = Pesos |
| 14 | payments | Numérico | - | Cantidad de cuotas seleccionada al momento de realizar el pago QR. |
| 22 | authorizationCode | Alfanumérico | - | Código de autorización informado por el Autorizador |
| 24 | trxId | Numérico | M | Identificador de la transacción. |
25 | dateTime | Numérico | M | 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 | M | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | M | Código de Respuesta emitido por el centro autorizador. 2 dígitos como máximo. Ver sección Códigos de Respuesta de VTOL Server para Billeteras Electrónicas |
28 | responseMessage | Alfanumérico | M | Mensaje de la Respuesta relacionado con el código del campo 27 |
29 | serialNumber | Numérico | O | Número identificatorio de la terminal en la que se procesó la transacción. Retorna en operaciones aprobadas. |
31 | lotNumber | Numérico | O | Número de lote en el que se registró la transacción |
32 | ticket | Numérico | O | Mensaje de repuesta para imprimir en el ticket del POS. Retorna en operaciones aprobadas. Contiene información generada por el Autorizador. |
| 54 | additionalAmount | Importe | 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. |
| 81 | responseAuth | Alfanumérico | O | Mensaje de repuesta para imprimir en el ticket del POS. Retorna en operaciones aprobadas. Contiene información generada por el Autorizador. Respuesta de este campo: COMPRA QR |
| 140 | paymentType | Numérico | - | Tipo de pago. Valores posibles: 0: Tarjeta |
| 142 | providerName | Alfanumérico | - | Proveedor de la tarjeta seleccionada al momento de efectuar el pago QR. |
| 147 | providerPosCode | Alfanumérico | - | Código del Provider. Retornará cuando la transacción fue aprobada por el Autorizador. |
| 157 | customerDoc | Numérico | O | Numero de documento del titular de la tarjeta. |
| 303 | customerName | Alfanumérico | O | Nombre del titular de la tarjeta. |
| 166 | trxReferenceNumber | Numérico | M | 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 | - | Identificador del número de pago informado por el Autorizador |
| 272 | amountRefunded | Importe | - | Monto devuelto en la transacción |
| 273 | paymentStatus | Alfanumérico | - | Estado de la transacción de pago informado por el Autorizador. Estados posibles: 0: Aprobado |
| 274 | paymentStatusDetail | Alfanumérico | - | Detalle del estado de la transacción de pago informado por el Autorizador |
| 275 | cardType | Numérico | - | Tipo de 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. Valores posibles: 0: Débito |
| 306 | cardIssuingBank | Alfanumérico | - | Banco emisor de la tarjeta. Retornará cuando la transacción fue aprobada por el Autorizador. |
| 404 | paymentOptionId | Alfanumérico | - | Identificador de la opción de pago seleccionada por el cliente en su billetera virtual. Según la tarjeta, el banco, y las cuotas elegidas por el cliente, se identificará con el paymentOptionId enviado por la caja. |
| 405 | benefitCardId | Alfanumérico | - | Identificador de la tarjeta de beneficio aplicada en el pago por estar vinculada en la billetera virtual del cliente. |
| 406 | originalAmount | Importe | - | Monto original de la transacción: de venta o de devolución. |
| 407 | amountDiscounted | Importe | - | Contiene el importe que se descontó sobre el importe original. Debido a la aplicación de una tarjeta de beneficio vinculada en la billetera virtual del cliente. Sólo retorna cuando se aplicó un descuento. |
| 428 | TID | Alfanumérico (long. 15) | ID de transacción de la marca para pagos ydevoluciones aprobadas de los siguientes medios de pago: | |
| 1010 | currentSessionId | Numérico | M | Identificador de la sesión |
| 1027 | libResponseCode | Numérico | M | Código de respuesta de la librería. Indica cómo fue procesada la operación en EMVKIT: Éxito = 000 |
| 1028 | libResponseMessage | Alfanumérico | M | Mensaje descriptivo del código de respuesta de la librería |