1.    Introducción

1.1.  Propósito

Definir los procesos y la mensajería de emvkit para operar con GOCuotas API QR. 

2. GOCuotas API QR

• Procesar Intención de compra Aprobado (saleWallet)

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

1. Envío de la transacción:
   El POS envía la transacción de venta (SaleWallet) a VTOL.

2. Autenticación:
   VTOL envía una solicitud de autenticación a GoCuotas mediante el endpoint /api/qr/v1/authentication.

   • Nota: El mensaje de solicitud se envía solo si no existe un authToken vigente. La vigencia de cada authToken es de 24 horas.

3. Recepción del token:
   GoCuotas responde a VTOL con un mensaje HTTP 200, donde se incluye el Token de autenticación aprobado. Este token será utilizado en futuras interacciones con la API de GoCuotas.

4. Intención de pago:
   VTOL se comunica con GoCuotas para enviar la intención de pago mediante un POST al endpoint /api/qr/v1/checkouts.

5. Confirmación del pago:

   • GoCuotas responde con el mensaje HTTP 201 "Orden creada".

     • En la respuesta se incluyen varios campos, como el sale_token, status, amount_in_cents, entre otros. El sale_token es el token que representará la venta y será utilizado en futuros requests.

   • VTOL recibe la notificación de que la orden fue creada.

   • Importante: Después de la creación de la orden de pago, VTOL tiene un plazo de 15 minutos para confirmar el pago. Si se excede el tiempo, la compra será cancelada automáticamente.

6. VTOL recibe el mensaje de que la orden fue creada:
   • Importante: Luego de la creación de la orden de pago, VTOL tiene un plazo de 15 minutos para confirmar el pago. Si se excede el tiempo establecido, la compra será cancelada automáticamente.

7. Escenarios posibles:

   • Pago aprobado: Si el usuario escanea el QR y selecciona la tarjeta de débito/cuotas para realizar el pago dentro del tiempo establecido (15 min), entonces VTOL recibe la notificación de la compra con el estado de la orden confirmada (status: approved), ya que el pago fue realizado con éxito.

     • Respuesta a POS: VTOL responde al POS con el estado de la transacción aprobada (isoCode 00 y responseMessage Aprobada).

   • Pago cancelado: Si el tiempo para completar el pago expira (15 min), VTOL recibe la notificación de que la compra fue cancelada (status: denied).

     • Respuesta a POS: VTOL responde al POS con la información de la orden cancelada.

8. Notificación a webhook:

   • La información sobre la confirmación o cancelación del pago se enviará al webhook_url proporcionado al momento de crear la venta con QR. El webhook será enviado en formato JSON.

   • Si el cliente realizó el pago, el webhook de confirmación se enviará de inmediato.

   • Si el cliente no realiza el pago en el plazo establecido, el webhook de cancelación será enviado a los 15 minutos.

9. Devolución de datos adicionales al POS :

   1. En la respuesta de pago aprobado, se deben retornar los siguientes campos adicionales:

      1. walletTransactionId (422): El ID de la transacción proporcionado por GoCuotas.

      2. cardNumber (6): El número de tarjeta utilizado para el pago.

      3. providerName (142): El nombre del proveedor de la tarjeta.

   2. Estos campos se obtienen realizando una consulta adicional a GoCuotas a través del endpoint /api/qr/v1/orders para consultar el estado de la transacción y extraer la información del pago aprobado.

   3. Los campos obtenidos de GoCuotas deben ser persistidos en la base de datos de VTOL y enviados en la respuesta a POS.

10. Confirmación final:
    Después de la confirmación del pago, el POS envía el tercer mensaje de “Commit”.

11. Finalización del flujo:
    El flujo de la operación SaleWallet se completa tras la confirmación o cancelación del pago, con la información final del estado de la transacción enviada al POS.

Nota: la información de la confirmación o cancelación del pago será enviando al webhook_url que se completó al momento de crear la venta con QR. El mismo será un POST con formato JSON. En el caso de confirmación de pago por parte del cliente, el webhook será enviado en el momento. Por otro lado, si el cliente no realiza el pago, el webhook de cancelación de venta será enviado a los 15 minutos.

      8. Se continua con el flujo 7.a. El POS envía el tercer mensaje de “Commit”.

      9. Finaliza el flujo de la operación.

• Diagrama de secuencia del Pago con envío de notificación en tiempo (orden confirmada "Approved")

• Procesar Devolución (RefundWallet):

A continuación, se define el flujo de RefundWallet con GoCuotas versión API QR:

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: si la devolución es por el monto total de la compra, se deberá enviar en el campo 12 el importe total o si el importe que se desea devolver es menor al total de la compra, se deberá enviar el importe en dicho campo, y se refiere a una compra parcial.
2. VTOL se comunica con GoCuotas mediante al endpoint /api/qr/v1/orders para consultar el estado de la orden, en donde se envía el saleToken que identifica la transacción original que se desea devolver.
3. GoCuotas 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 solicitar la devolución parcial o total. Una orden se marca como confirmada luego de que el usuario realiza el pago de forma exitosa.
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.
5. El POS le envía a VTOL el tercer mensaje "Commit".
6. VTOL se comunica con GoCuotas mediante el endpoint api/qr/v1/refund para solicitar la devolución total o parcial de una venta. Se envían los parámetros sale_token y amount_in_cents.
7. GoCuotas le responde a VTOL con datos de la transacción como el status, order_reference_id, amount_in_cents, entre otros.
8. Finaliza el flujo de la operación.

• Diagrama de secuencia operación "RefundWallet"

A continuación, se agrega el flujo de operación en donde se envía desde el POS la solicitud de Rollback y la orden se encuentra en estado Approved, la cual termina en un RefundWallet:

• Procesar consulta (QueryWallet):

A continuación, se define el flujo de la operación QueryWallet en GoCuotas API QR:

1. El POS le envía a VTOL la operación “QueryWallet” con el campo 268: WalletPosTrxId.
2. VTOL se comunica con GoCuotas mediante el endpoint /checkouts/{api_qr_sale_token}, en donde se deberá enviar un sale_token válido. Nota: VTOL solo se comunica con GoCuotas si el pago no está aprobado. Si el pago se encuentra aprobado, entonces VTOL le responde automáticamente al POS con la información de la orden aprobada, sin realizar la consulta a GoCuotas.
3. GoCuotas le responde a VTOL el código HTTP 200 con el status de la operación y los otros campos definidos por GoCuotas.
4. VTOL le responde al POS el estado Aprobado de la operación solicitada (saleWallet o refundWallet).

• Mensajería POS - VTOL de las transacciones SaleWallet, RefundWallet y QueryWallet

• • Request POS - VTOL:

Referencias:

X = Mandatorio

O = Opcional

- = No requerido

Ejemplo log .lib:

• • Response VTOL - POS

Referencias:

X = Mandatorio

O = Opcional

- = No requerido

Ejemplo log lib: