Contenido
Revisiones
Fecha | Versión | Descripción |
---|---|---|
01/07/2024 | 1.0 | Creación del documento |
1. Introducción
1.1. Propósito y audiencia
Definir los procesos, diagramas y mensajería de las operaciones saleWallet, RefundWallet y reversos de los pagos realizados con PRISMA QR Sistemas Propios - Transferencias 3.0.
1.2 Referencias
Referencia | Descripción |
---|---|
VTOL QR Prisma Transferecia 3.0 on Vimeo | Video de la configuración de PRISMA QR Transferencias 3.0 |
2. Procesar el pago con Transferencias 3.0 (SaleWallet)
La opción de pago que debe enviar la caja es la siguiente:
{ "providerPosCode": "TR", "installments": [ {"quantity": "1", "amountPerInstallment": 1500, "totalAmount": 1500, "surcharge": 0, "nominalAnnualRate": "0"} ] }
2.1 Definición del flujo y Diagrama del proceso pago con Transferencia 3.0
2.1.1 Procesar pago con el envío de notificación en tiempo
A continuación, se definen los pasos del flujo:
- El POS envía la transacción de venta (SaleWallet) a VTOL con el providerPosCode: “TR”.
- VTOL se comunica con PRISMA QR para enviar la creación de la intención de compra al endpoint [POST] /integrations/intentions. Se envía el CBU y el payment_method_id: 112
- 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 y el campo status: “created”.
- VTOL recibe el mensaje de que la orden fue creada correctamente y le informa al POS en los campos 27 isoCode: "516" y 28 responseMessage: "Operación aún no realizada, consulte nuevamente”. Luego se envían las QueryWallet del POS a VTOL para consultar por el estado del pago.
- 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. El usuario visualizará el detalle de la compra con las opciones de pago disponibles y efectuará el pago seleccionando la tarjeta y las cuotas, de esta forma se confirma el pago.
- PRISMA autoriza la compra y envía la Notificación de compra a VTOL.
- VTOL recibe el estado de la operación. Se pueden presentar los siguientes escenarios:
- Si el pago se realizó correctamente, entonces VTOL recibe la respuesta del estado de la orden "Approved", por lo cual, se incrementa el ticket y trace de la caja en donde se realizó la operación. 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 en tiempo, entonces desde el POS se envían las consultas. Ver Flujo alterno
- Fin del flujo definido en el diagrama 4.1 Pago con el envío de notificación en tiempo.
2.1.2 Diagrama de secuencia del proceso "Pago con el envío de notificación en tiempo":
2.1.3 Procesar pago sin el envío de la notificación
A continuación, se definen los pasos del flujo en donde se expira el tiempo de espera para realizar el pago y VTOL no recibe la notificación de compra:
- El POS envía la transacción de venta (SaleWallet) a VTOL con el providerPosCode: “TR”.
- VTOL se comunica con PRISMA QR para enviar la creación de la intención de compra al endpoint [POST] /integrations/intentions. Se envía el CBU y el payment_method_id: 112
- 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 y el campo status: “created”.
- VTOL recibe el mensaje de que la orden fue creada correctamente y le informa al POS en los campos 27 isoCode: "516" y 28 responseMessage: "Operación aún no realizada, consulte nuevamente”. Luego se envían las QueryWallet del POS a VTOL para consultar por el estado del pago.
- POS le envía a VTOL una queryWallet para consultar el estado del pago, VTOL le responde al POS código 514("Tiempo expirado. Elija Consultar o Cancelar pago")
- VTOL envía un mensaje a Prisma informando que expiró el tiempo de la notificación.
- 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. El usuario visualizará el detalle de la compra con las opciones de pago disponibles y efectuará el pago seleccionando la tarjeta y las cuotas, de esta forma se confirma el pago.
- VTOL consulta a PRISMA el estado de la compra mediante el endpoint [GET] api/integrations/payments/qr?intention_id={value}.
- PRISMA responde con el código http 200 y los datos de la operación con en "status": "approved".
- VTOL le responde al POS con el estado de la transacción aprobada (isoCode "00" y responseMessage "Aprobada").
- El paso siguiente del POS es confirmaro cancelar la transacción, con un tercer mensaje.
2.1.4 Diagrama de secuencia del proceso "Pago sin el envío de notificación":
2.2 Especificación de los campos en la mensajería para “Procesar pagos con transferencias 3.0”
A continuación, se especifican todos los campos de las distintas mensajerías del proceso:
2.2.1 Mensajería POS - VTOL para la transacción "SaleWallet".
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
Referencia de campos:
- M = Mandatorio.
- O = Opcional.
- - = No requerido.
- C = Condicional.
Número | Nombre del campo | Tipo de dato | SaleWallet | Descripción | EMVKit - VTOL |
---|---|---|---|---|---|
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:
| Informa el mismo campo y valor a VTOL |
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". | Informa el mismo campo y valor a VTOL |
13 | currencyPosCode | Alfanumérico | M | Tipos de moneda: $ = Pesos | Informa el mismo campo y valor a VTOL |
16 | originalDate | Numérico | - | Fecha de realización de la compra con billetera electrónica en formato YYYYMMDD | Informa el mismo campo y valor a VTOL |
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. | Informa el mismo campo y valor a VTOL |
25 | dateTime | Numérico | M | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS | Informa el mismo campo y valor a VTOL |
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. | Informa el mismo campo y valor a VTOL |
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. | Informa el mismo campo y valor a VTOL |
270 | walletPosTicket | Alfanumérico | M | Información del ticket en formato xml y posteriormente transformado en Base 64. | |
271 | walletPaymentId | Alfanumérico | - | 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. | Informa el mismo campo y valor a VTOL |
401 | walletPaymentMethod | Formato Json | M | Información de los planes de pago en formato json. Nota: la estructura de este campo está definida en la siguiente sección del documento. Importante: para realizar el pago con transferencia 3.0 se debe agregar la opción de pago "TR" en providerPosCode. | |
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. 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 del campo paymentMethodsData (401) con los sub-campos obligatorios para un pago con transferencias:
|
Estructura del campo walletBenefit (402)
El mensaje con la estructura de los beneficios estará en JSON. Estará conformado 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". | |
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 del campo walletBenefits (402)
|
Ejemplo Request SaleWallet (log emvkit):
Request: {270:PG1lc3NhZ2UgY29tcGFueUlkPSJzdHMiIHN0b3JlPSIwMDAwMSIgdGVybWluYWw9IjAxMCIgZGF0ZS10aW1lPSIyMDE3LTEyLTA0IDEyOjMwOjAwOiIgbWVzc2FnZUlkPSIwMDEwIiB2b2lkLXRyeD0iZmFsc2UiIHJlc3BvbnNlPSJ0cnVlIiBpbml0LXRjaz0idHJ1ZSIgZXZhbHVhdGU9InRydWUiIHN0 YXR1cz0icGF5bWVudCIgbXNnLXZlcnNpb249IjIuMCIgbWFwLXZlcnNpb249IjE1Ij4KCTxpdGVtLWFkZCBzZXE9IjEiIGNvZGU9IjAwMDEiIGRpc2NvdW50YWJsZT0idHJ1ZSIgdW5pdHByaWNlPSIxLjAiIHF0eT0iMTUuMCIgbGV2ZWwxPSJOQUZUQSIgbGV2ZWwyPSJQUkVNSVVNIiBzdXBwbGllcj0i IiBicmFuZD0iWVBGIiB4cHJpY2U9IjE1LjAiIG1hZ25pdHVkZT0iMS4wIiBkZXNjcmlwdGlvbj0iQ29tYnVzdGlibGUgUFJFTUlVTSIgY3VycmVuY3k9IiQiIC8+CjwvbWVzc2FnZT4K;269:3;268:0000000001000000000120242004102023;13:$;12:1500;11:SaleWallet;402:[{"benefitCardId"\: "01"\, "providerPosCode"\: "CLN"\, "discountPercentage"\: "2500"\, "maximumDiscountAmount"\: "000"}\, {"benefitCardId"\: "02"\, "providerPosCode"\: "CC"\, "discountPercentage"\: "1000"\, "maximumDiscountAmount"\: "000"}] ;401:[ { "providerPosCode"\: "TR"\, "installments"\: [{ "paymentOptionId"\: "123" \,"quantity"\: "1"\, "amountPerInstallment"\: 1500\, "totalAmount"\: 1500\, "surcharge"\: 0\, "nominalAnnualRate"\: "0" }] } ] ;2:1;25:20240704102023;1:1;0:1}
- 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. |
6 | cardNumber | Alfanumérico | O | Tarjeta enmascarada seleccionada por el cliente al momento de efectuar el pago QR. Nota: 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. 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. |
15 | plan | Numérico | M | Plan de pago. Campo de1 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 | businessNumber | Numérico | O | 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. |
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. |
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. Nota: este campo contiene "Transferencias 3.0". Se debe crear en la base de datos. |
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. |
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 | - | 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 | 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. |
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 SaleWallet (log emvkit):
Response message: {0:1;1:1;2:1;1027:000;1028:Ok;140:1;12:1500;13:$;14:1;142:Transferencias3.0;271:1823819240704;15:0;272:00;273:0;274:approved;275:0;147:TR;404:123;406:1500;22:HMN5TO;24:7;25:20240704102116;26:ISO8583;27:00;28:APROBADA;29:90000505;30:29880765;31:1;32:6;1010:1720099220076}
3. Procesar la Devolución de pago con transferencia 3.0
3.1 Definición del flujo
A continuación, se define el flujo de la operación 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. Se crea una transacción offline en estado "pending". En este punto se pueden presentar los siguientes escenarios:
- El POS 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 el código HTTP 201 "created" que contiene en el body 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".
- Fin del flujo 4.a.
- El POS envía a VTOL el tercer mensaje "Rollback":
- Se elimina la transacción offline y la venta queda aprobada, la devolución cancelada.
- El POS envía a VTOL el tercer mensaje "Commit":
- Fin del flujo.
3.2 Diagrama de secuencia
3.3 Especificación de los campos en la mensajería para “Procesar la devolución de un pago con transferencias 3.0”
A continuación, se especifican todos los campos de las distintas mensajerías del proceso:
3.3.1 Mensajería POS - VTOL para la transacción "RefundWallet".
- Request POS - VTOL
Referencia de campos:
- M = Mandatorio.
- O = Opcional.
- - = No requerido.
- C = Condicional.
Número | Nombre del campo | Tipo de dato | RefundWallet | Descripción | EMVKit - VTOL |
---|---|---|---|---|---|
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:
| Informa el mismo campo y valor a VTOL |
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". | Informa el mismo campo y valor a VTOL |
13 | currencyPosCode | Alfanumérico | M | Indica el tipo de moneda: $ = Pesos | Informa el mismo campo y valor a VTOL |
16 | originalDate | Numérico | M | Fecha de realización de la compra con billetera electrónica en formato YYYYMMDD | Informa el mismo campo y valor a VTOL |
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. | Informa el mismo campo y valor a VTOL |
25 | dateTime | Numérico | M | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS | Informa el mismo campo y valor a VTOL |
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. | Informa el mismo campo y valor a VTOL |
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. | Informa el mismo campo y valor a VTOL |
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. | Informa el mismo campo y valor a VTOL |
Ejemplo Request RefundWallet (log emvkit):
Request: {271:0000000001000000000120243104053105;269:10;16:20240404;268:0000000001000000000120243204053203;13:$;12:8100;11:RefundWallet;2:1;25:20240404173203;1:1;0:1} |
- Response VTOL - POS
En el siguiente cuadro se informa la mensajería de requerimiento entre POS - EMV KIT AR - 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 |
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. |
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 RefundWallet (log emvkit):
4. Procesar el Reverso del pago aprobado con transferencia 3.0
4.1 Definición del flujo
A continuación, se definen los pasos del flujo:
- El POS envía la transacción de venta (SaleWallet) a VTOL con el providerPosCode: “TR”.
- VTOL se comunica con PRISMA QR para enviar la creación de la intención de compra al endpoint [POST] /integrations/intentions. Se envía el CBU y el payment_method_id: 112
- 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 y el campo status: “created”.
- VTOL recibe el mensaje de que la orden fue creada correctamente y le informa al POS en los campos 27 isoCode: "516" y 28 responseMessage: "Operación aún no realizada, consulte nuevamente”. Luego se envían las QueryWallet del POS a VTOL para consultar por el estado del pago.
- 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. El usuario visualizará el detalle de la compra con las opciones de pago disponibles y efectuará el pago seleccionando la tarjeta y las cuotas, de esta forma se confirma el pago.
- PRISMA autoriza la compra y envía la Notificación de compra a VTOL.
- VTOL recibe la respuesta del estado de la orden "Approved" y 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 POS envía un Rollback (tercer mensaje del POS).
- VTOL le consulta a PRISMA el estado de la compra mediante el endpoint [GET] /payments/qr?intention_id={value}. PRISMA responde el código http 200 con los datos de la operación y el status: "appoved".
- VTOL se comunica con PRISMA mediante el endpoint [POST] /forcedrefunds, en donde envía el parámetro "intention_id", entre otros.
- PRISMA responde con el código http 404 y el "status": "rejected", ya que al verificar que es una operación SaleWallet de "Transferencia 3.0", se ignora la solicitud de Rollback, por lo cual será anulada y el estado de la transacción pasa a Commit.
- Finaliza el flujo de la operación.
4.2 Diagrama del proceso
4.3 Especificación de los campos en la mensajería para “Procesar el reverso de un pago con transferencias 3.0”
A continuación, se especifican todos los campos de las distintas mensajerías del proceso:
4.3.1 Mensajería POS - VTOL
- Request POS - VTOL
Referencia de campos:
- M = Mandatorio.
- O = Opcional.
- - = No requerido.
- C = Condicional.
A continuación, se especifican los campos de la mensajería de Emvkit y VTOL que se envían en el mensaje de requerimiento al realizar la operación "Rollback" de un pago aprobado con transferencia:
Número | Nombre del campo | Tipo de dato | Rollback | 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 | O | Identificador del Server que procesará la transacción. (en el caso de VTOL será 'VTOL'). Este campo pertenece a la mensajería de VTOL y no de Emvkit. El campo pertenece únicamente a la mensajería de VTOL. |
4 | messageType | Indica el tipo de Mensaje:
Exclusivo para mensajería POS-VTOL. | ||
11 | trxType | Alfanumérico | M | Tipo de Transacción:
|
19 | lastTrxAction | Alfanumérico | O | Acción a realizar sobre la Transacción:
El campo pertenece únicamente a la mensajería de VTOL. |
24 | lastTrxId | Numérico | O | Id de transacción a confirmar / reversar. El campo pertenece únicamente a la mensajería de VTOL. |
25 | dateTime | Numérico | M | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
1008 | closeSessionAction | Numérico | M | Acción que se debe realizar sobre el cierre de sesión:
|
Ejemplo mensajería POS - VTOL:
19 lastTrxAction : Rollback 11 trxType : UnSyncCompletion 4 messageType : DATA 3 server : VTOL 2 node : 1 25 dateTime : 20230616155611 1 store : 1 24 lastTrxId : 313
- Response VTOL - POS
A continuación, se especifican los campos de la mensajería Emvkit correspondiente al mensaje de respuesta de VTOL hacia el POS de la operación "Rollback":
Número | Nombre del campo | Tipo de dato | Rollback | Descripción |
1010 | currentSessionId | Numérico | X | Identificador de la sesión actual. |
1027 | libResponseCode | Numérico | X | Código de respuesta de la librería. Indica cómo fue procesada la operación en EMVKIT: Éxito = 000 Error <> 000 Ver sección Códigos de Respuesta de Librería Mensaje descriptivo del código de respuesta de la librería |
1028 | libResponseCode | Alfanumérico | X | Mensaje descriptivo del código de respuesta de la librería |