...
VTOL EMVKIT AR 1.11.X - Prisma QR Grandes Cuentas
...
| Painel | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
Revisiones
Fecha | Versión | Descripción |
|---|---|---|
| 01/07/2024 | 1.0 | Creación del documento |
| 2/10/2025 | 1.1 | Se especifica que se debe agregar el plan de pago Transferencia "TR" obligatoriamente en el campo 401 en el mensaje de QueryWallet de "Intención de compra completa" |
1. Introducción
1.1. Propósito
...
- 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. Nota: si hay algún beneficio adicional de una tarjeta, la información se enviará en el campo 402 "walletBenefit". Esta queryWallet indica que se debe enviar el mensaje a Prisma 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.
...
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. |
...
| [{"posCode":"VI","bank_id":7,"bin":459354}] |
Ejemplo Response QueryWallet (log emvkitEstructura del campo 401 (walletPaymentMethod):
Response message:
...
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.
| |
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} |
...
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 campo VTOL envía el valor de los providers que tiene el cliente en su billetera.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. |
...
| 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.
| |
...
| 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. | |
...
Request: {269:3;16:20250415;268:0000000015000007048620251415041408;12:140000;11:QueryWallet;401:[ |
...