Contenido
Revisiones
Fecha | Versión | Descripción |
---|---|---|
25/06/2024 | 1.0 | Se agrega el proceso y la mensajería de GOCuotas API QR en el manual de emvkit |
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:
- El POS envía la transacción de venta (SaleWallet) a VTOL.
- VTOL le envía a GoCuotas el requerimiento de Authenticacion al endpoint /api/qr/v1/authentication. Nota: el request message solo se envía si no existe un authToken vigente, la vigencia de cada authToken es de 24 hs
- GoCuotas responde a VTOL con el message HTTP 200 en donde le envía el Token de autenticación aprobado.
- VTOL se comunica con GoCuotas para enviar la intención de pago mediante un POST al endpoint /api/qr/v1/checkouts.
- GoCuotas responde con el mensaje HTTP 201 "Orden creada" y algunos campos en el messagge response como el sale_token, status, amount_in_cents, entre otros. El campo sale_token será el token que representará la nueva venta y que se deberá enviar en algunos requests.
- VTOL recibe el mensaje de que la orden fue creada. Importante: luego de la creación de la orden de pago, se tienen 15 min para realizar la confirmación del pago, si se excede el tiempo establecido, la compra será cancelada automáticamente.
- Se pueden presentar los siguientes escenarios:
- 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 usuario realizó el pago de forma exitosa. Luego VTOL le responde al POS con el estado de la transacción aprobada (isoCode "00" y responseMessage "Aprobada").
- Si expiró el tiempo establecido de los 15 min para realizar el pago, entonces, VTOL recibe la notificación de la compra con el estado cancelada (status: denied). En este caso, la orden se cancela de forma automáticamente. Luego VTOL le responde al POS con la información de la orden cancelada.
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:
- 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.
- 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.
- 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.
- VTOL le responde al POS con el estado de la orden confirmada, con el campo 27 isoCode = 00 y el campo 28 responseMessage = Aprobada.
- El POS le envía a VTOL el tercer mensaje "Commit".
- 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.
- GoCuotas le responde a VTOL con datos de la transacción como el status, order_reference_id, amount_in_cents, entre otros.
- Finaliza el flujo de la operación.
Importante:
- Se pueden realizar devoluciones por el monto total de la transacción y también por un monto parcial.
- Las devoluciones se deben realizar desde la misma caja donde se realizó la venta original.
Diagrama de secuencia operación "RefundWallet"
IMPORTANTE:
Las devoluciones se deben realizar desde la misma caja donde se realizó la venta original.
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:
- El POS le envía a VTOL la operación “QueryWallet” con el campo 268: WalletPosTrxId.
- 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.
- GoCuotas le responde a VTOL el código HTTP 200 con el status de la operación y los otros campos definidos por GoCuotas.
- 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
Número | Nombre del campo | Tipo de dato | SaleWallet | RefundWallet | QueryWallet | Descripción |
0 | company | Numérico | X | X | X | Identificador de la compañía donde se generó la transacción. |
1 | store | Numérico | X | X | X | Identificador del sitio originador de la transacción |
2 | node | Alfanumérico | X | X | X | Identificación del nodo, en el sitio originador, donde se generó la transacción |
3 | server | Alfanumérico | X | X | - | Identificador del Server que procesará la transacción. (en el caso de VTOL será 'VTOL') |
4 | messageType | Alfanumérico | X | X | - | Tipo de Mensaje:
|
11 | trxType | Alfanumérico | X | X | X | Tipo de Transacción:
|
12 | amount | Importe | X | X | - | Monto de la transacción. Valor entero. Los últimos 2 dígitos corresponden a los decimales. |
13 | currencyPosCode | Alfanumérico | X | X | - | Tipos de moneda:
|
16 | originalDate | Numérico | - | X | X | Fecha de realización de la compra con billetera electrónica en formato YYYYMMDD |
24 | trxId | Numérico | - | O | - | Identificador de la transacción |
25 | dateTime | Numérico | X | X | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
71 | checkPendingString | Alfanumérico | X | X | - | Indica si VTOL debe o no efectuar el chequeo de pendientes:
|
157 | customerDoc | Numérico | X | - | - | Número de documento del cliente que realiza la consulta. Valida la cantidad de dígitos ingresados, máximo 8 dígitos. |
268 | walletPosTrxId | Alfanumérico | X | X | X | Identificador único de la transacción de billetera para la compañía. Debe ser único por tipo de transacción. Es originado por el POS para realizar una compra o devolución con billetera. Formato: |
269 | walletType | Numérico | X | X | X | Tipo de billetera por la cual se cursará la transacción en el POS. Opciones: 1: Mercado Pago 5: Yacaré 6: Plus Pagos 8: Rappi Payless 10: GoCuotas |
270 | walletPosTicket | Alfanumérico | X | - | - | Información del ticket en formato xml y posteriormente transformado en Base 64. Ver sección Estructura del campo posTicket |
271 | walletPaymentId | Numérico | - | - | Identificador del número de pago informado por el Autorizador. | |
416 | customerPhoneAreaCode | Numérico | O | - | - | Código de área de teléfono celular del cliente. Valida la cantidad de dígitos, máximo 5 dígitos. No se envía el 0 en el código de área. |
417 | customerPhone | Numérico | O | - | - | Teléfono celular del cliente. Valida la cantidad de dígitos ingresados, máximo 9 dígitos. |
418 | customerEmail | Alfanumérico | O | - | - | Mail del cliente. Valida el formato del mail: [email protected] |
Ejemplo log .lib:
Request to VTOL (SaleWallet): Request: {418:li@gmail.com;417:58888888;416:11;270:PG1lc3NhZ2UgY29tcGFueUlkPSJzdHMiIHN0b3JlPSIwMDAwMSIgdGVybWluYWw9IjAxMCIgZGF0 Request to VTOL (RefundWallet): Request: {271:0000000001000000000120243104053105;269:10;16:20240404;268:0000000001000000000120243204053203;13:$;12:8100;11:RefundWallet;2:1;25:20240404173203;1:1;0:1} Request to VTOL (QueryWallet): Request: {269:10;16:20240408;268:0000000001000000000120245308035340;25:20240408155500;2:1;1:1;11:QueryWallet} |
- Response VTOL - POS
Referencias:
X = Mandatorio
O = Opcional
- = No requerido
Número | Nombre del campo | Tipo de dato | SaleWallet | RefundWallet | QueryWallet | Descripción |
0 | company | Numérico | X | O | O | Identificador de la compañía donde se generó la transacción. |
1 | store | Numérico | X | X | X | Identificador del sitio originador de la transacción |
2 | node | Alfanumérico | X | X | X | Identificación del nodo, en el sitio originador, donde se generó la transacción |
12 | amount | Importe | X | - | X | Monto de la transacción. Valor entero. Los últimos 2 dígitos corresponden a los decimales. |
13 | currencyPosCode | Alfanumérico | X | - | X | Tipos de moneda:
|
24 | trxId | Numérico | X | X | X | Identificador de la transacción |
25 | clientDate | Numérico | X | X | X | Fecha y hora de realización de la transacción en formato YYYYMMDDHHMMSS |
26 | responseCode | Alfanumérico | X | X | X | Puede contener uno de los siguientes valores:
|
27 | isoCode | Numérico | X | X | X | Código de Respuesta emitido por el centro autorizador. 3 dígitos como máximo. Ver sección Códigos de respuesta VTOL Server para GoCuotas |
28 | responseMessage | Alfanumérico | X | X | X | Mensaje de la Respuesta relacionado con el código del campo 27 |
140 | paymentType | Numérico | X | - | X | Tipo de pago. Valore posible 0: Tarjeta |
166 | trxReferenceNumber | Numérico | X | X | O | 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 | X | - | X | Identificador del número de pago informado por el Autorizador. |
273 | paymentStatus | Alfanumérico | X | - | X | Estado de la transacción de pago informado por el Autorizador. Estados posibles: 0: Aprobado |
274 | paymentStatusDetail | Alfanumérico | - | X | X | Detalle del estado de la transacción de pago informado por el Autorizador |
275 | cardType | Numérico | X | - | X | Tipo de tarjeta seleccionada al momento de efectuar el pago. Valor posible: |
Ejemplo log lib:
SaleWallet: Response message: {1:1;2:1;166:14021905052200000204;271:2289999999999999228;22:1234567;24:121;25:20190214050518;26:ISO8583;27:00;28:APROBADA} RefundWallet: Response message: {0:1;1:1;2:1;1010:1712262719597;1027:000;1028:Ok;166:4042417320700000087;24:45;25:20240404173203;26:ISO8583;27:00;28:APROBADA} QueryWallet: Response message: {1:1;2:1;1027:000;1028:Ok;12:210000;140:0;13:$;14:2;271:0000000001000000000120245308035340;273:0;274:approved;1010:1712602498527;275:0;24:10;25:20240408155500;26:ISO8583;27:00;28:APROBADA} |