VTOL EMVKIT AR 1.11.X - Fiserv QR Mensajería

Revisiones

1.    Introducción

1.1.  Propósito

Definir los procesos, y la mensajería para operar con FISERV QR. 

2. Procesar mensaje FISERV QR

2.1 Integración

VTOL se integra con QR Adquiriente de Fiserv para permitir efectuar pagos en los puntos de venta con billeteras electrónicas. En el pinpad se imprime el código QR en pantalla, el cual siempre es dinámico, es decir que se genera uno nuevo por cada transacción.

Las operaciones soportadas son:

• SaleWallet = Permite realizar una compra presencial con billetera electrónica.
• RefundWallet = Permite realizar una devolución con Adquiriente Fiserv. 
• QueryWallet = Permite realizar una consulta de una operación de compra con billetera para conocer si la misma fue autorizada y así obtener los datos por parte del Autorizador.

Flujo y Diagrama de secuencia del "Pago con Tarjeta" (una interacción). Finaliza el flujo con un cerrar sesión (CLOSE)

A continuación, se define el flujo de la operación:

1. El POS envía un SaleWallet con el ammount (campo 12), paymments (campo 14) y el provider (campo 147).
2. VTOL le envía a Fiserv la solicitud de compra con billetera digital, enviado el message Code 0200 y el processing code 0060031.
3. Fiserv responde con la información del código QR mediante el message code 9600 y el  processing code 940400 y VTOL confirma la recepción del QR con el código de mensaje 9610.
4. VTOL envía el código QR en el campo 410 "QRCode" y luego se despliega en el pinpad el QR dinámico para ser escaneado por la billetera virtual del cliente.
5. El cliente escanea el QR y selecciona la Tarjeta para confirmar el pago.
6. VTOL responde al POS el código 657 "QR recibido, consulte el procesamiento del pago".
7. VTOL valida el BIN y compara con el provider (campo 147) enviado por el POS, luego le envía a Fiserv la respuesta con los datos para autorizar el pago.
8. Fiserv autoriza el pago y le envía a VTOL la respuesta con los datos de la solicitud (message code 0210).
9. El POS envía un QueryWallet para obtener los datos del pago.
   
   1. Si el pago está aprobado, VTOL le responde al POS el código 00 "Aprobado"
10. El POS confirma la operación enviando un Cierre de sesión en estado CLOSE.
11. VTOL envía la confirmación de la compra (message code 0202) y Fiserv responde con el código 0212.
12. Finaliza el flujo.

Flujo y Diagrama de secuencia del "Pago con Tarjeta" (una interacción) con error. Finaliza el flujo con un cerrar sesión (CANCEL)

En este flujo se presenta un error en VTOL al validar el BIN y al comparar el provider (campo 147) enviado por el POS. Por este motivo, el flujo finaliza con un cerrar sesión (CANCEL). A continuación, se define el flujo de la operación:

1. El POS envía un SaleWallet con el ammount (campo 12), paymments (campo 14) y el provider (campo 147).
2. VTOL le envía a Fiserv la solicitud de compra con billetera digital, enviado el message Code 0200 y el processing code 0060031.
3. Fiserv responde con la información del código QR mediante el message code 9600 y el  processing code 940400 y VTOL confirma la recepción del QR con el código de mensaje 9610.
4. VTOL envía el código QR en el campo 410 "QRCode" y luego se despliega en el pinpad el QR dinámico para ser escaneado por la billetera virtual del cliente.
5. El cliente escanea el QR y selecciona la Tarjeta para confirmar el pago.
6. VTOL responde al POS el código 657 "QR recibido, consulte el procesamiento del pago".
7. Error en VTOL al validar el BIN y comparar con el provider (campo 147) enviado por el POS, luego VTOL le envía a Fiserv la solicitud de Cancel (message code 0420).
8. Fiserv responde la solicitud del cancel (message code 0430)
9. El POS envía un QueryWallet para obtener los datos del pago. VTOL responde el código 553 "Pago rechazado".
10. El POS cancela la operación enviando un cierre de sesión en estado CANCEL.
11. Finaliza el flujo.

Diagrama y Flujo del "Pago con Tarjeta" (dos interacciones) y Pago con dinero en cuenta

Flujo de Pago Unificado:

Inicio del flujo (común para ambos tipos de pago)

1. El POS envía un SaleWallet con el monto y las cuotas de la operación (cuotas=0).

2. Se despliega el QR dinámico en el pinpad para ser escaneado por la billetera virtual del cliente.

A. Pago con Tarjeta

1. El cliente escanea el QR y selecciona la Tarjeta en su app bancaria.

2. VTOL responde al POS con el código 657 (QR recibido, consulte el procesamiento del pago).

3. El POS envía un QueryWallet para obtener los datos del pago.

4. VTOL responde cuál fue la Tarjeta elegida por el cliente, con el código 654 (Valide monto y cuotas según tarjeta elegida) y hace un eco del monto y las cuotas originales enviadas por el POS.

5. El POS envía un nuevo QueryWallet, enviando los campos de monto y cuotas, pudiendo modificar ambos datos.

   • a. Si el POS no envía los campos de monto y cuotas, VTOL responderá nuevamente con el código 654 (Valide monto y cuotas según tarjeta elegida).

   • b. Si el pago aún no se ha realizado, VTOL le responde al POS con el código 516 ("Pago aún no realizado").

6. El POS envía un nuevo QueryWallet para consultar el estado del pago. Si el pago está autorizado, VTOL responde con los datos del pago y le envía al POS el código 00 "Aprobado".

7. El POS confirma la operación enviando un Cierre de sesión en estado CLOSE.

8. VTOL envía la confirmación de la compra (message code 0202) y Fiserv responde con el código 0212.

9. Finaliza el flujo.

B. Pago con Dinero en Cuenta

1. VTOL responde al POS con el código 657 (QR recibido, consulte el procesamiento del pago).

2. El cliente escanea el QR y selecciona la Cuenta bancaria para confirmar el pago.

3. El POS envía un QueryWallet para obtener los datos del pago.

   • a. Si el pago se realizó, VTOL le responde al POS con los datos del pago y el código 00 "Aprobado".

4. El POS confirma la operación enviando un Cierre de sesión en estado CLOSE.

5. VTOL envía a Fiserv la confirmación y Fiserv responde con el código 0212.

6. Finaliza el flujo.

Flujos alternativos de secuencia del "Pago con dinero en cuenta"

A continuación, se detallan 3 flujos alternativos del Diagrama Pago con dinero en cuenta:

a._ La caja desea cancelar el pago con saldo en cuenta y NO es permitido:

Si la caja desea enviar un reverso de un pago con dinero en cuenta, la caja deberá enviar primero a VTOL un QueryWallet con el campo 420 "precancel" en valor true, el cual indica que es una consulta previa para ejecutar un cancel, es decir, no se puede enviar un reverso directamente.

Si la respuesta de la QueryWallet que tiene el precancel en true informa el pago Aprobado (00), entonces se le informa el POS que NO se puede cancelar el pago y luego el POS envía el cerrar sesión (CLOSE).  Nota: en este escenario se puede proceder con la devolución del pago ya que se encuentra aprobado.

En el diagrama de secuencia se encuentra resaltado en rojo el resumen del flujo de este escenario:

b._ La caja desea cancelar el pago con saldo en cuenta y SI es permitido

Si la caja desea enviar un reverso de un pago con dinero en cuenta, la caja le deberá enviar primero a VTOL un QueryWallet con el campo 420 "precancel" en valor true, el cual indica que es una consulta previa para ejecutar un cancel, es decir, no se puede enviar un reverso directamente.

Si la respuesta de la QueryWallet que tiene el precancel en true se le informa al POS que el pago aún no está Aprobado (código 516) le permite al POS realizar la acción de cerrar sesión (CANCEL)

En el diagrama de secuencia se encuentra resaltado en azul el resumen del flujo de este escenario:

c._ Error en la comunicación entre Fiserv y VTOL.

Si VTOL no recibe información de Fiserv acerca del pago en el tiempo definido, VTOL le envía un reverso a Fiserv al cual le responde con el código B6 "No se puede realizar el reverso del pago porque está autorizado".

A continuación, se especifica el flujo:

1. El POS envía un SaleWallet con el monto y las cuotas de la operación.
2. Se despliega en el pinpad el QR dinámico para ser escaneado por la billetera virtual del cliente.
3. El cliente escanea el QR y selecciona la Cuenta y confirma el pago.
4. VTOL responde al POS el código 657 (TQR recibido, consulte el procesamiento del pago).
5. El POS envía un QueryWallet para obtener los datos del pago. El pago aún no se ha realizado, por lo cual, VTOL responde con el código 516 “Pago aún no realizado, Consulte o Cancele el pago”.
6. Fiserv autoriza el pago, pero hay un error en la comunicación, por este motivo, Fiserv no le puede enviar a VTOL la respuesta del pago.
7. VTOL le envía la solicitud de reverso a Fiserv, debido a que se excede el tiempo establecido para recibir los datos del pago.
8. VTOL recibe la respuesta de Fiserv con el código B6 “No se puede realizar el reverso del pago porque está autorizado".
9. El POS envía un QueryWallet y VTOL le consulta a Fiserv por el pago pendiente. Fiserv le responde a VTOL los datos del pago Aprobado.
10. El POS confirma la operación enviando un Cierre de sesión en estado CLOSE.
11. VTOL envía un commit con la confirmación y Fiserv responde el código 0212 con la confirmación.

Diagrama de secuencia

En el diagrama se encuentra resaltado en verde el resumen de este proceso:

Flujo de la Devolución (RefundWallet):

El flujo consiste en:

1. El POS envía a VTOL un RefundWallet con el número de operación de la compra y el monto original para solicitar la devolución.
2. VTOL envía la solicitud de la devolución a Fiserv con el código de mensaje 0400 y el código de procesamiento correspondiente a la transacción original.
3. Fiserv responde con la información del código QR y VTOL confirma la recepción del QR.
4. VTOL envía los datos del código QR para que el usuario pueda seleccionar en su billetera la opción de “Devolución” sobre el pago que quiere anular.
5. Se despliega en el pinpad el QR dinámico para ser escaneado por la billetera virtual del cliente y luego confirmar la Devolución de la transacción en la aplicación.
6. Fiserv le envía la respuesta a VTOL para confirmar la devolución con el código 0410.
7. El POS envía un QueryWallet a VTOL para obtener los datos de la devolución.
8. VTOL responde los datos de la devolución.
9. El POS confirma la operación enviando un Cerrar sesión (Commit) a VTOL.
10. VTOL envía un mensaje a Fiserv para confirmar la Devolución mediante el código de mensaje 0202.
11. Fiserv responde la confirmación de la Devolución a VTOL mediante el código de mensaje 0212.
12. Finaliza el flujo.

Diagrama de secuencia

2.2 Mensajería

• Requerimiento

Estructura del campo posTicket (270)

El mensaje con la estructura del ticket estará en XML. El elemento raíz de ese mensaje XML deberá ser la etiqueta <message>, siendo la misma lo que se llamará encabezado.

Dentro del encabezado, se podrá enviar el valor de los descuentos totales y de los impuestos totales que aplicarán a la compra.

Los campos dentro del encabezado serán: totDiscount y totTaxes

Detalle de los campos:

La manera de ejecutar un comando es utilizando una etiqueta con la forma <elemento-comando>. El elemento "item" identifica a los artículos. De esta manera, si se desea, por ejemplo, agregar un nuevo artículo el comando a utilizar será <item-add>. En el cuerpo del mensaje podrá contener uno, ninguno o varios de estos comandos. 

Cada uno de los comandos que se envían posee diversos atributos, los cuales identifican al elemento que se está enviando y definen diversas propiedades que poseen los mismos. Poseerá un número de secuencia, el cual identifica cada elemento unívocamente:

Cada comando posee una serie de atributos que definirán las distintas propiedades del elemento que se está agregando (además del número de secuencia antes mencionado).

Para el elemento ítem, los atributos serán los siguientes:

Ejemplo

<message totDiscount="10.00" totTaxes="5.00">
 <item-add seq="1" code="0001" discountable="true" unitprice="25.0" qty="1.0" level1="MEN" level2="CASUAL" supplier="" brand="LEVIS" xprice="25.0" magnitude="1" description="Jean casual" currency="$" />
 <item-add seq="2" code="0002" discountable="true" unitprice="28.0" qty="2.0" level1="MEN" level2="CASUAL" supplier="" brand="LEVIS" xprice="48.0" magnitude="1" description="Jean casual" currency="$" />
</message>

• Respuesta

2.3 Ejemplos de logs

2.3.1 Pago con Tarjeta (dos interacciones)

***** El POS crea la intención de pago:
Request: {270:PG1lc3NhZ2U+CjxpdGVtLWFkZCBjdXJyZW5jeT0iJCIgZGVzY3JpcHRpb249IkdlbmVyaWMgRGVz
Y3JpcHRpb24iIHF0eT0iMS4wIiBzZXE9IjEiIHVuaXRwcmljZT0iMTYzMC45OCIgeHByaWNlPSIx
NjMwLjk4Ii8+CjwvbWVzc2FnZT4K;269:7;268:00000055300000000005250319161540;14:1;13:$;12:163098;11:SaleWallet;1410:true;2:5;25:20250319161540;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;166:19032516163300002994;12:00;272:00;1010:1742411740101;24:106;25:20250319161540;410:000201010212263000112008341948301110000000000043350010com.fiserv981130692264785990200501500112008341948351260022000006800000000222295652045812530303254071630.985802AR5908DorinkaQ6012VILLA GESELL6105071656267012042000000000000000000052137888861174241179654207083788886108020080500010com.fiserv010502.020202010312250319161636040126304a0f5;26:ISO8583;27:657;28:QR recibido\, consulte el procesamiento del pago;29:37888861;30:000020083419483}

***** Consulta para obtener los datos del medio de pago:
Request: {271:19032516163300002994;16:20250319;269:7;268:00000055300000000005250319161540;13:$;11:QueryWallet;2:5;25:20250319161540;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;12:163098;140:0;13:$;14:1;271:000190600057;273:0;1010:1742411740101;275:0;24:106;25:20250319161540;26:ISO8583;27:516;28:Pago aun no realizado\, desea seguir esperando?;511:FiservQR}

***** Otra consulta para obtener los datos del medio de pago. Retorna la tarjeta elegida por el usuario en la app bancaria:
Request: {271:19032516163300002994;16:20250319;269:7;268:00000055300000000005250319161540;13:$;11:QueryWallet;2:5;25:20250319161540;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;140:0;12:163098;13:$;14:0;142:Master Card;271:000190600057;273:654;1010:1742411740101;275:1;147:MC;24:106;25:20250319161540;26:ISO8583;27:654;28:Valide monto y cuotas seg?n tarjeta elegida;511:FiservQR}

***** El POS envía Monto y Cuotas definitivas:
Request: {271:000190600057;269:7;16:20250319;268:00000055300000000005250319161540;14:1;13:$;12:163098;11:QueryWallet;2:5;25:20250319161623;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;140:0;12:163098;13:$;14:1;142:Master Card;271:000190600057;273:516;1010:1742411740101;275:1;147:MC;24:106;25:20250319161623;26:ISO8583;27:516;28:Pago aun no realizado\, desea seguir esperando?;511:FiservQR}

***** Consulta para obtener el estado del pago:
Request: {271:000190600057;269:7;16:20250319;268:00000055300000000005250319161540;14:1;13:$;12:163098;11:QueryWallet;2:5;25:20250319161623;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;140:0;12:163098;13:$;14:1;142:Master Card;271:000190600057;273:516;1010:1742411740101;275:1;147:MC;24:106;25:20250319161623;26:ISO8583;27:516;28:Pago aun no realizado\, desea seguir esperando?;511:FiservQR}

***** Otra consulta para obtener el estado del pago. La operación retorna APROBADA:
Request: {271:000190600057;269:7;16:20250319;268:00000055300000000005250319161540;14:1;13:$;12:163098;11:QueryWallet;2:5;25:20250319161623;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;140:0;12:163098;13:$;14:1;142:Master Card;271:000190600057;273:0;274:approved;1010:1742411740101;275:1;147:MC;6:451756xxxxxx0001;29:37888861;22:560789;24:106;25:20250319161623;26:ISO8583;27:00;28:APROBADA;511:MODO}

***** El POS cierra sesión confirmando OK:
Request: {1009:{106};1008:CLOSE;2:5;1:5530;11:closeSession}

Response message: {1010:1742411740101;1027:000;1028:Ok}

2.3.2 Pago con Dinero en Cuenta (PCT)

***** El POS inicia sesión:

Request: {25:20250401140711;2:5;1:5530;11:createSession;0:7TY02}

Response message: {1010:1743527231299;1027:000;1028:Ok}

***** El POS crea la intención de pago:

Request: {270:PG1lc3NhZ2U+CjxpdGVtLWFkZCBjdXJyZW5jeT0iJCIgZGVzY3JpcHRpb249IkdlbmVyaWMgRGVz
Y3JpcHRpb24iIHF0eT0iMS4wIiBzZXE9IjEiIHVuaXRwcmljZT0iMTk4OS4wMCIgeHByaWNlPSIx
OTg5LjAwIi8+CjwvbWVzc2FnZT4K;269:7;268:00000055300000000005250401140711;14:0;13:$;12:198900;11:SaleWallet;1410:true;2:5;25:20250401140711;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;166:1042514081200003456;12:00;272:00;1010:1743527231299;24:403;25:20250401140711;410:000201010212263000112008341948301110000000000043350010com.fiserv981130692264785990200501500112008341948351260022000006800000000222295652045812530303254071989.005802AR5908DorinkaQ6012VILLA GESELL6105071656267012018500000000000000000052137888861174352729643407083788886108020080500010com.fiserv010502.02020201031225040114081604012630442e6;26:657;27:657;28:QR recibido\, consulte el procesamiento del pago;29:37888861;30:000020083419483}

***** Consulta para obtener los datos del medio de pago:

Request: {271:1042514081200003456;269:7;16:20250401;268:00000055300000000005250401140711;13:$;12:198900;11:QueryWallet;2:5;25:20250401140717;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;12:198900;140:2;13:$;14:0;271:000010600049;273:0;1010:1743527231299;275:0;24:403;25:20250401140717;26:ISO8583;27:516;28:Pago aun no realizado\, desea seguir esperando?;511:FiservQR}

***** Otra consulta para obtener los datos del medio de pago. Retorna que el pago se realizó con Dinero en Cuenta:

Request: {271:1042514081200003456;269:7;16:20250401;268:00000055300000000005250401140711;13:$;12:198900;11:QueryWallet;2:5;25:20250401140717;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;140:2;12:198900;13:$;14:0;271:000010600049;273:0;274:approved;1010:1743527231299;275:0;22:Q0M51O;24:403;25:20250401140717;26:ISO8583;27:00;28:APROBADA;511:MODO}

***** El POS cierra sesión confirmando OK:

Request: {1009:{403};1008:CLOSE;2:5;1:5530;11:closeSession}

Response message: {1010:1743527231299;1027:000;1028:Ok}

2.3.3 Devolución

***** El POS crea la intención de devolución:
Request: {271:000190600057;269:7;16:20250319;268:00000055300000000005250319161826;13:$;12:163098;11:RefundWallet;1410:true;2:5;25:20250319161826;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;166:19032516191600002995;272:00;1010:1742411906967;24:107;25:20250319161826;410:000201010212501500112008341948351260022000006800000000222295652045812530303254071630.985802AR5908DorinkaQ6012VILLA GESELL6105071656243052137888861174241195911707083788886108020280440010com.fiserv010502.010312250319161919040126304012d;26:657;27:657;28:QR recibido\, consulte el procesamiento del pago}

***** Consulta para obtener los datos de la devolución:
Request: {271:19032516191600002995;269:7;16:20250319;268:00000055300000000005250319161826;13:$;12:163098;11:QueryWallet;2:5;25:20250319161834;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;12:163098;140:0;13:$;14:1;271:000190600059;273:0;1010:1742411906967;275:0;24:107;25:20250319161834;26:ISO8583;27:516;28:Pago aun no realizado\, desea seguir esperando?;511:FiservQR}

***** Otra consulta para obtener los datos de la devolución:
Request: {271:19032516191600002995;269:7;16:20250319;268:00000055300000000005250319161826;13:$;12:163098;11:QueryWallet;2:5;25:20250319161834;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;12:163098;140:0;13:$;14:1;271:000190600059;273:0;1010:1742411906967;275:0;24:107;25:20250319161834;26:ISO8583;27:516;28:Pago aun no realizado\, desea seguir esperando?;511:FiservQR}

***** Otra consulta para obtener los datos de la devolución:
Request: {271:19032516191600002995;269:7;16:20250319;268:00000055300000000005250319161826;13:$;12:163098;11:QueryWallet;2:5;25:20250319161834;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;140:0;12:163098;13:$;14:1;142:Master Card;271:000190600059;273:654;1010:1742411906967;275:1;147:MC;24:107;25:20250319161834;26:ISO8583;27:516;28:Pago aun no realizado\, desea seguir esperando?;511:FiservQR}

***** Otra consulta para obtener los datos de la devolución. La devolución retornó Aprobada:
Request: {271:19032516191600002995;269:7;16:20250319;268:00000055300000000005250319161826;13:$;12:163098;11:QueryWallet;2:5;25:20250319161834;1:5530}

Response message: {0:7TY02;1:5530;2:5;1027:000;1028:Ok;140:0;12:163098;13:$;14:1;142:Master Card;271:000190600059;273:0;274:approved;1010:1742411906967;275:1;147:MC;22:502694;24:107;25:20250319161834;26:ISO8583;27:00;28:APROBADA;511:MODO}

***** El POS cierra sesión confirmando OK:
Request: {1009:{107};1008:CLOSE;2:5;1:5530;11:closeSession}

Response message: {1010:1742411906967;1027:000;1028:Ok}