Contenido


Revisiones

Fecha

Versión

Descripción

01/07/20241.0Creació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 VimeoVideo 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:

  1. El POS envía la transacción de venta (SaleWallet) a VTOL con el providerPosCode: “TR”.
  2. 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
  3. 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”.
  4. 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.
  5. 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. 
  6. PRISMA autoriza la compra y envía la Notificación de compra a VTOL.
  7. VTOL recibe el estado de la operación. Se pueden presentar los siguientes escenarios:
    1. 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.
    2. 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
  8. 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:

  1. El POS envía la transacción de venta (SaleWallet) a VTOL con el providerPosCode: “TR”.
  2. 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
  3. 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”.
  4. 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.
  5. 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")
  6. VTOL envía un mensaje a Prisma informando que expiró el tiempo de la notificación.
  7. 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. 
  8. VTOL consulta a PRISMA el estado de la compra mediante el endpoint [GET] api/integrations/payments/qr?intention_id={value}.
  9. PRISMA responde con el código http 200 y los datos de la operación con en "status": "approved".
  10. VTOL le responde al POS con el estado de la transacción aprobada (isoCode "00" y responseMessage "Aprobada").
  11. 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

0companyNuméricoM

Identificador de la compañía donde se generó la transacción. Exclusivo para mensajería POS-VTOL.


1storeAlfanuméricoM

Identificador del local donde se generó la transacción. Exclusivo para mensajería POS-VTOL.


2nodeNuméricoM

Identificador de la caja donde se generó la transacción. Exclusivo para mensajería POS-VTOL.


3serverAlfanuméricoM

Identificador del Server que procesará la transacción, en el caso de VTOL será "VTOL". Exclusivo para mensajería POS-VTOL.


4messageTypeAlfanuméricoM

Indica el tipo de mensaje:

  • Control = Mensaje de Control, para uso interno por parte de un módulo en su comunicación con el server.
  • Data = Mensaje de la Aplicación cliente.

Exclusivo para mensajería POS-VTOL.


11trxTypeAlfanuméricoM

Indica el tipo de transacción:

  • SaleWallet = Compra con billetera electrónica.
Informa el mismo campo y valor a VTOL
12amountNuméricoMMonto 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
13currencyPosCodeAlfanuméricoM

Tipos de moneda: $ = Pesos

Informa el mismo campo y valor a VTOL
16originalDateNumérico-Fecha de realización de la compra con billetera electrónica en formato YYYYMMDDInforma el mismo campo y valor a VTOL
24

lastTrxId

NuméricoOEn 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
25dateTimeNuméricoMFecha y hora de realización de la transacción en formato YYYYMMDDHHMMSSInforma el mismo campo y valor a VTOL
268walletPosTrxIdAlfanuméricoM

Identificador único de la transacción de billetera para la compañía. Es originado por el POS para realizar una compra con billetera.

Formato:
codigoTienda (longitud 10) + codigoCaja (longitud 10) + Fecha (AAMMDDHHmmss) (longitud 12)
Longitud total de 32.

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
269walletTypeNuméricoM

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
270walletPosTicketAlfanuméricoM

Información del ticket en formato xml y posteriormente transformado en Base 64.


271walletPaymentIdAlfanumé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 JsonM

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 JsonOInformación de las tarjetas de beneficio aceptadas.


Estructura del campo 401 (walletPaymentMethod):

Referencia de campos:

  • M = Mandatorio.
  • O = Opcional.
ParámetroTipo de datoReferenciaDescripción
providerPosCodeAlfanuméricoM

Código del Proveedor de la tarjeta configurado en VTOL.

Nota: para Transferencias 3.0 corresponde a "TR".

bankCodeNuméricoO

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.

installmentsArrayMInformación de las cuotas.

paymentOptionId


AlfanuméricoM

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.

quantityNuméricoM

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éricoO

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.

amountPerInstallmentImporteM

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.

totalAmountImporteM

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.

surchargeDecimalM

Porcentaje de recargo sobre las cuotas. Valor entero. Los 2 últimos dígitos corresponden a los decimales.

  • Recargo (C.F.T. - costo financiero total): porcentaje.

Nota: para transferencias 3.0 el valor de este campo es 0, ya que no existe recargo.

nominalAnnualRateDecimalM

Tasa Nominal Anual. Valor entero. Los 2 últimos dígitos corresponden a los decimales.

  • T.N.A. (tasa nominal anual): porcentaje.


Ejemplo del campo paymentMethodsData (401) con los sub-campos obligatorios para un pago con transferencias:

{
"providerPosCode": "TR",
"installments": [{
    "paymentOptionId": "1"
    "quantity": "1",
    "amountPerInstallment": 150000,
    "totalAmount": 150000,
    "surcharge": 0,
    "nominalAnnualRate":0
    }]
}


Estructura del campo walletBenefit (402)

El mensaje con la estructura de los beneficios estará en JSON. Estará conformado por los siguientes campos:

ParámetroTipo de datoRequeridoDescripción

benefitCardId

AlfanuméricoSi

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.

providerPosCodeAlfanuméricoSiCódigo de la tarjeta de beneficio configurada en VTOL. Por ejemplo, para Clarin 365 el código es "CC".

discountPercentage

NuméricoSiPorcentaje de descuento a aplicar sobre la compra. Valor entero. Los 2 últimos dígitos corresponden a los decimales.

maximumDiscountAmount

NuméricoSiImporte 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)

[
   {
      "benefitCardId":"01",
      "providerPosCode":"CLN",
      "discountPercentage":"2500",
      "maximumDiscountAmount":"000"
   },
   {
      "benefitCardId":"02",
      "providerPosCode":"CC",
      "discountPercentage":"1000",
      "maximumDiscountAmount":"000"
   }
]


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

0companyNuméricoMIdentificador de la compañía donde se generó la transacción
1storeAlfanuméricoMIdentificador del sitio originador de la transacción
2nodeNuméricoMIdentificación del nodo, en el sitio originador, donde se generó la transacción.
6cardNumber AlfanuméricoO

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.

12amountImporteM

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.

13currencyPosCodeAlfanuméricoM

Tipos de moneda: $ = Pesos

14paymentsNuméricoM

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éricoM

Plan de pago. Campo de1 carácter de longitud.

Nota: si el pago se realiza por Transferencias, el campo toma el valor de 0.

22authorizationCodeAlfanuméricoM

Código de autorización informado por el Autorizador

24trxIdNuméricoMIdentificador 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:

  • ISO8583 = la autorización fue procesada. Para evaluar si fue aprobada chequear el campo 27
  • Error = ver sección Códigos de error del CORE
  • TrxIsPending: indica si existen transacciones pendientes de confirmar. En este caso, el ID de transacción a confirmar está en el campo 24.

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.

54additionalAmount

Importe

OContiene el Importe del "Cashout". Aplica para las operaciones realizadas con retiro de efectivo. Valor entero. Los últimos 2 dígitos corresponden a los decimales.
81responseAuthAlfanuméricoOMensaje de repuesta para imprimir en el ticket del POS. Retorna en operaciones aprobadas. Contiene información generada por el Autorizador.
140paymentTypeNumérico-

Tipo de pago. Valores posibles:

0: Tarjeta
1: Efectivo

142providerNameAlfanumé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. 

147providerPosCodeAlfanuméricoO

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"

157customerDocNuméricoONumero de documento del titular de la tarjeta.
303customerNameAlfanuméricoONombre del titular de la tarjeta.
166trxReferenceNumberNuméricoMIdentificador ú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

MIdentificador del número de pago informado por el Autorizador
272amountRefundedImporte-Monto devuelto en la transacción
273paymentStatusAlfanumérico-

Estado de la transacción de pago informado por el Autorizador. Estados posibles:

0: Aprobado
1: Devuelto
2: Pendiente
3: Autorizado
4: En Progreso
6: Rechazado
7: Cancelado
8: Contracargo

274paymentStatusDetailAlfanumérico-Detalle del estado de la transacción de pago informado por el Autorizador
275cardTypeNumé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
1: Crédito

306cardIssuingBankAlfanuméricoOBanco emisor de la tarjeta. Retornará cuando la transacción fue aprobada por el Autorizador.
404

paymentOptionId

AlfanuméricoM

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éricoOIdentificador de la tarjeta de beneficio aplicada en el pago por estar vinculada en la billetera virtual del cliente. 
406originalAmountImporteMMonto original de la transacción: de venta o de devolución.
407

amountDiscounted

ImporteO

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.

1010currentSessionIdNuméricoMIdentificador de la sesión
1027libResponseCodeNuméricoM

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

1028libResponseMessageAlfanuméricoMMensaje 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:

  1. 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.
  2. 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.
  3. 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.
  4. 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: 
    1. El POS envía a VTOL el tercer mensaje "Commit":
      1. 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.
      2. 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.
      3. 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".
      4. Fin del flujo 4.a.
    2. El POS envía a VTOL el tercer mensaje "Rollback":
      1. Se elimina la transacción offline y la venta queda aprobada, la devolución cancelada.
  5. 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
0companyNuméricoM

Identificador de la compañía donde se generó la transacción. Exclusivo para mensajería POS-VTOL. 


1storeAlfanuméricoM

Identificador del local donde se generó la transacción. Exclusivo para mensajería POS-VTOL.


2nodeNuméricoM

Identificador de la caja donde se generó la transacción. Exclusivo para mensajería POS-VTOL.


3serverAlfanuméricoM

Identificador del Server que procesará la transacción, en el caso de VTOL será 'VTOL'. Exclusivo para mensajería POS-VTOL.


4messageTypeAlfanuméricoM

Indica el tipo de Mensaje:

  • Control = Mensaje de Control, para uso interno por parte de un módulo en su comunicación con el server.
  • Data = Mensaje de la Aplicación cliente.

Exclusivo para mensajería POS-VTOL.


11trxTypeAlfanuméricoM

Tipo de Transacción:

  • RefundWallet = Devolución de compra realizada con billetera electrónica
Informa el mismo campo y valor a VTOL
12amountNuméricoMMonto 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
13currencyPosCodeAlfanuméricoM

Indica el tipo de moneda: $ = Pesos

Informa el mismo campo y valor a VTOL
16originalDateNuméricoMFecha de realización de la compra con billetera electrónica en formato YYYYMMDDInforma el mismo campo y valor a VTOL
24

lastTrxId

NuméricoOEn 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
25dateTimeNuméricoMFecha y hora de realización de la transacción en formato YYYYMMDDHHMMSSInforma el mismo campo y valor a VTOL
268walletPosTrxIdAlfanuméricoM

Identificador único de la transacción de billetera para la compañía. Es originado por el POS para realizar una compra con billetera.

Formato:
codigoTienda (longitud 10) + codigoCaja (longitud 10) + Fecha (AAMMDDHHmmss) (longitud 12)
Longitud total de 32.

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
269walletTypeNuméricoM

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
271walletPaymentIdAlfanuméricoM

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

0companyNuméricoMIdentificador de la compañía donde se generó la transacción
1storeAlfanuméricoMIdentificador del sitio originador de la transacción
2nodeNuméricoMIdentificación del nodo, en el sitio originador, donde se generó la transacción.
6cardNumberAlfanumérico-Tarjeta enmascarada seleccionada por el cliente al momento de efectuar el pago QR.
12amountImporte-

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.

13currencyPosCodeAlfanumérico-

Tipo de moneda: $ = Pesos

14paymentsNumérico-Cantidad de cuotas seleccionada al momento de realizar el pago QR.
22authorizationCodeAlfanumérico-

Código de autorización informado por el Autorizador

24trxIdNuméricoMIdentificador 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:

  • Iso8583 = la autorización fue procesada. Para evaluar si fue aprobada chequear el campo 27
  • Error = ver sección Códigos de error del CORE
  • TrxIsPending: indica si existen transacciones pendientes de confirmar. En este caso, el ID de transacción a confirmar está en el campo 24

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.

54additionalAmountImporteOContiene el Importe del "Cashout". Para aquellas operaciones realizadas con retiro de efectivo. Valor entero. Los últimos 2 dígitos corresponden a los decimales.
81responseAuthAlfanuméricoOMensaje 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
140paymentTypeNumérico-

Tipo de pago. Valores posibles:

0: Tarjeta
1: Efectivo

142providerNameAlfanumérico-Proveedor de la tarjeta seleccionada al momento de efectuar el pago QR. 
147providerPosCodeAlfanumérico-Código del Provider. Retornará cuando la transacción fue aprobada por el Autorizador.
157customerDocNuméricoONumero de documento del titular de la tarjeta.
303customerNameAlfanuméricoONombre del titular de la tarjeta.
166trxReferenceNumberNuméricoMIdentificador ú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
272amountRefundedImporte-Monto devuelto en la transacción
273paymentStatusAlfanumérico-

Estado de la transacción de pago informado por el Autorizador. Estados posibles:

0: Aprobado
1: Devuelto
2: Pendiente
3: Autorizado
4: En Progreso
6: Rechazado
7: Cancelado
8: Contracargo

274paymentStatusDetailAlfanumérico-Detalle del estado de la transacción de pago informado por el Autorizador
275cardTypeNumé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
1: Crédito

306cardIssuingBankAlfanumé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.
406originalAmountImporte-Monto original de la transacción: de venta o de devolución.
407amountDiscountedImporte-

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.

1010currentSessionIdNuméricoMIdentificador de la sesión
1027libResponseCodeNuméricoM

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

1028libResponseMessageAlfanuméricoMMensaje 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:

  1. El POS envía la transacción de venta (SaleWallet) a VTOL con el providerPosCode: “TR”.
  2. 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
  3. 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”.
  4. 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.
  5. 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. 
  6. PRISMA autoriza la compra y envía la Notificación de compra a VTOL.
  7. 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").
  8. El POS envía un Rollback (tercer mensaje del POS).
  9. 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".
  10. VTOL se comunica con PRISMA mediante el endpoint [POST] /forcedrefunds, en donde envía el parámetro "intention_id", entre otros.
  11. 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.
  12. 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:

  • Control = Mensaje de Control, para uso interno por parte de un módulo en su comunicación con el server.
  • Data = Mensaje de la Aplicación cliente.

Exclusivo para mensajería POS-VTOL.

11

trxType

Alfanumérico

M

Tipo de Transacción:

  • UnSyncCompletion = Mensaje de completamiento de transacción (“tercer mensaje”)

19

lastTrxAction

Alfanumérico

O

Acción a realizar sobre la Transacción:

  • Rollback = Reversa 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:

  • CANCEL = Reversar las autorizaciones realizadas en la sesión. Al realizar el cierre se sesión Cancel (Rollback), se deberá enviar en el campo 1008 el valor CANCEL.

Ejemplo mensajería POS - VTOL:

Request message
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

  • Sem rótulos