Histórico da Página

...

...

Âncora
_Toc485222716 _Toc485222716

1.2 Protocolo de comunicación POS – VTOL Server

Synthesis Napse establece un protocolo de comunicación para la interacción POS - VTOL, el cual se denomina "Protocolo VTOL". Dicho protocolo se basa en un esquema recursivo compuesto por campos y separadores. A continuación se provee una especificación detallada de su estructura junto con los consecuentes diagramas para un mejor entendimiento.
Para implementar esta mensajería, VTOL provee una librería en el cual se encuentra la declaración de funciones y las definiciones de constantes y tipos necesarias. La librería es en realidad un módulo cliente que se comunica vía TCP/IP con el servidor de transacciones VTOL. El cliente podrá implementar esta mensajería sin utilizar la librería, pero deberá respetar el formato de la misma.
El formato del protocolo VTOL se basa en la siguiente estructura:

...

...

...

1. Campo 27: Código de Respuesta
2. Campo 28: Descripción de la Respuesta

...

...

Código

...

Descripción

1.4.28 Operaciones GoCuotas API QR

VTOL se integra con GoCuotas API QR para permitir efectuar pagos mediante un código QR estático por cada caja, en modalidad presencial, desde un punto de venta (POS). Al enviar la intención de compra desde VTOL a GoCuotas, se habilitará un QR que el usuario comprador deberá escanear desde la cámara de su celular y se le redireccionará a la web de GoCuotas, en donde deberá tener una cuenta registrada con una tarjeta de débito para realizar el pago. El encargado de aprobar los pagos es GOCUOTAS, quien es el encargado también de la gestión e impresión de los códigos QR. Luego VTOL deberá recibir mediante una notificación la respuesta con el estado de la orden, ya sea Confirmado o Cancelado.

Las transacciones soportadas son:

• SaleWallet = Permite realizar una compra presencial con billetera electrónica.
• RefundWallet = Permite realizar una devolución (parcial o total) de una compra presencial con billetera realizada con anterioridad.
• 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

Definición del flujo de la operación SaleWallet:

1. El POS envía la transacción de venta (SaleWallet) a VTOL.
2. 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
3. GoCuotas responde a VTOL con el message HTTP 200 en donde le envía el Token de autenticación aprobado.
4. VTOL se comunica con GoCuotas para enviar la intención de pago mediante un POST al endpoint /api/qr/v1/checkouts. 
5. 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.
6. 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.
7. Se pueden presentar los siguientes escenarios:
   1. 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"). 
   2.  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.

Definición del 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: 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. 

Definición del flujo de la operación QueryWallet:

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).

1.4.28.1 Requerimiento POS - VTOL

1.4.28.2 Respuesta VTOL - POS

1.4.29 Operaciones GoCuotas API Full

VTOL se integra con la API Full de GOCUOTAS para permitir a los comercios aceptar esta billetera como un método de pago adicional. GoCuotas, es una billetera que permite realizar el pago con tarjeta de DEBITO de una compra hasta en 4 cuotas sin interés. Se realizarán pagos con la Billetera GOCUOTAS, en modalidad presencial, desde un punto de venta (POS). El encargado de aprobar los pagos será GOCUOTAS. VTOL enviará una intención de pago, y esperará recibir la respuesta del mismo, ya sea Aprobado o Rechazado.

En la versión API Full de GoCuotas al ingresar todos los datos para generar una venta, se le enviará un código de verificación al celular del cliente que se le deberá solicitar luego para realizar la validación de identidad y poder completar la venta. Se puede agregar una nueva tarjeta que se utilizará para completar la venta (solo es necesario para clientes nuevos o clientes que necesiten utilizar otra tarjeta). También se pueden realizar reembolsos por el monto total o parcial de la venta y consultar ordenes generadas. Las operaciones soportadas son las siguientes: 

• SaleWallet = Permite realizar una compra presencial con billetera electrónica.
• RefundWallet = Permite realizar una devolución (parcial o total) de una compra presencial con billetera realizada con anterioridad.
• 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

Definición del flujo de la operación SaleWallet:

1. Se inicia con el envío de una orden de venta (transacción SaleWallet) por parte del POS a VTOL.
2. VTOL le envía a GoCuotas el requerimiento de Authentication mediante el endpoint /authentication. Nota: el request message solo se envía si no existe un authToken vigente, la vigencia de cada authToken es de 24 hs.
3. GoCuotas responde a VTOL con el message HTTP 200 en donde se envía el Token de autenticación aprobado.
4. Luego VTOL se comunica con GoCuotas mediante endpoint / send_code, en donde se envían todos los datos necesarios para generar la venta: email, dni, area_code (sin "0"), telephone_number (sin "15"), amount_in_cents, number_of_installments, order_reference_id y Authorization: Bearer.
5. GoCuotas responde a VTOL con el Message HTTP 201 y el dato "sale_token" que será el token que representará la nueva venta.
6. VTOL le responde al POS el isocode 714 y el responseMessage “Orden creada, ingrese el código de verificación”
7. El POS le envía a VTOL el primer QueryWallet con el campo 279: softToken.
8. VTOL se comunica con GoCuotas mediante el endpoint /code_verification, en donde envía los campos sale_token, code y Authorization: Bearer. En este endpoint se envía el código de seguridad “code” que recibió el cliente en su celular para validar su identidad.
9. GoCuotas le responde a VTOL con el dato de la tarjeta (card) que contiene los últimos 4 dígitos y el status de la compra. GoCuotas responde con toda la información de la venta generada y con los datos del cliente.
10. VTOL le responde al POS con el isocode 718 y el responseMessage “Confirma la tarjeta recibida”.
11. El POS le envía a VTOL la segunda QueryWallet (se envía el campo 6: cardNumber con los últimos cuatro dígitos de la tarjeta como eco del campo 6 de la respuesta de VTOL al POS del paso anterior). 
12. VTOL se comunica con Gocuotas mediante al endpoint / payments (este endpoint se utiliza para realizar el pago y completar la venta).
13. GoCuotas responde a VTOL con el status aprobado de la transacción y otros datos.
14. VTOL le responde al POS con el estado de la transacción aprobada (isoCode "00" y responseMessage "Aprobada")
15. Por último, el POS envía el tercer mensaje de “Commit”.

Definición del flujo de la operación SaleWallet con cambio de tarjeta:

A continuación, se define el flujo para procesar un pago con cambio de tarjeta de débito "Aprobado":

1. Se inicia con el envío de una orden de venta (transacción SaleWallet) por parte del POS a VTOL.
2. VTOL le envía a GoCuotas el requerimiento de Authentication mediante el endpoint /authentication. Nota: el request message solo se envía si no existe un authToken vigente, la vigencia de cada authToken es de 24 hs.
3. GoCuotas responde a VTOL con el Message HTTP 200 en donde se envía el Token con la respuesta Aprobado.
4. Luego VTOL se comunica con GoCuotas mediante endpoint / send_code, en donde se envían todos los datos necesarios para generar la venta: el email, dni, area_code (sin "0"), telephone_number (sin "15"), amount_in_cents, number_of_installments, order_reference_id y Authorization: Bearer.
5. GoCuotas responde a VTOL con el Message HTTP 201 y el dato"sale_token" que será el token que representará la nueva venta.
6. VTOL le responde al POS el isocode 714 y el responseMessage “Orden creada, ingrese el código de verificación”
7. El POS le envía a VTOL el primer QueryWallet con el campo 279: softToken.
8. VTOL se comunica con GoCuotas mediante el endpoint / code_verification, en donde le envía los campos sale_token, code y Authorization: Bearer. En este endpoint se envía el código de seguridad “code” que recibió el cliente en su celular para validar su identidad.
9. GoCuotas le responde a VTOL con el dato de la tarjeta (card) que contiene los últimos 4 dígitos y el status de la compra. GoCuotas responde con toda la información de la venta generada y con los datos del cliente.
10. VTOL le responde al POS con el isocode 718 y el responseMessage “Confirma la tarjeta recibida”.
11. El POS le envía a VTOL la segunda QueryWallet con los campos, "6: cardNumber" (dieciséis dígitos de la tarjeta), "8: cvc" (tres dígitos), expirationDate (cuatro dígitos en formato AAMM).
12. VTOL le envía a GoCuotas el requerimiento del cambio de tarjeta mediante el endpoint / cards (este endpoint se utiliza en el caso de que el cliente no tenga ninguna tarjeta cargada en el sistema de GoCuotas o si es necesario cambiar de tarjeta para realizar el pago).
13. GoCuotas le responde a VTOL con los siguientes datos: sale_token, status, last_four_digits, entre otros.
14. VTOL le responde al POS con el isocode 718 y el responseMessage “Confirma la tarjeta recibida”.
15. El POS le envía a VTOL la tercera QueryWallet con el "campo 6: cardNumber".
16. VTOL se comunica con Gocuotas mediante al endpoint / payments  (este endpoint se utiliza para realizar el pago y completar la venta).
17. GoCuotas responde a VTOL con los campos payment_successfully_confirmed: true, "status": "approved", card, entre otros.
18. VTOL le envía al POS el response message "Aprobada".

Definición del flujo de la operación SaleWallet con cambio de tarjeta que excede el tiempo máximo (2min) para realizar el pago:

 A continuación, se define el flujo para procesar un pago con cambio de tarjeta superando el tiempo máximo (2min) para realizar el pago:

1. Se inicia con el envío de una orden de venta (transacción SaleWallet) por parte del POS a VTOL.
2. VTOL le envía a GoCuotas el requerimiento de Authentication mediante el endpoint /authentication. Nota: el request message solo se envía si no existe un authToken vigente, la vigencia de cada authToken es de 24 hs.
3. GoCuotas responde a VTOL con el Message HTTP 200 en donde se envía el Token con la respuesta Aprobado.
4. Luego VTOL se comunica con GoCuotas mediante endpoint / send_code, en donde se envían todos los datos necesarios para generar la venta: el email, dni, area_code (sin "0"), telephone_number (sin "15"), amount_in_cents, number_of_installments, order_reference_id y Authorization: Bearer.
5. GoCuotas responde a VTOL con el Message HTTP 201 y el dato del "sale_token" que será el token que representará la nueva venta.
6. VTOL le responde al POS el isocode 714 y el responseMessage “Orden creada, ingrese el código de verificación”
7. El POS le envía a VTOL el primer QueryWallet con el campo 279: softToken.
8. VTOL se comunica con GoCuotas mediante el endpoint / code_verification, en donde le envía los campos sale_token, code y Authorization: Bearer. En este endpoint se envía el código de seguridad “code” que recibió el cliente en su celular para validar su identidad.
9. GoCuotas le responde a VTOL con el dato de la tarjeta (card) que contiene los últimos 4 dígitos y el status de la compra. GoCuotas responde con toda la información de la venta generada y con los datos del cliente.
10. VTOL le responde al POS con el isocode 718 y el responseMessage “Confirma la tarjeta recibida”.
11. El POS le envía a VTOL la segunda QueryWallet con los campos, "6 cardNumber" (dieciséis dígitos de la tarjeta), "8 cvc" (tres dígitos), expirationDate (cuatro dígitos en formato AAMM). También se debe informar el campo "269 WalletType" con GoCuotas.
12. VTOL le envía a GoCuotas el requerimiento del cambio de tarjeta mediante el endpoint /cards (este endpoint se utiliza en el caso de que el cliente no tenga ninguna tarjeta cargada en en el sistema de GoCuotas o si es necesario cambiar de tarjeta para realizar el pago).
13. GoCuotas le responde a VTOL con los siguientes datos: sale_token, status, last_four_digits, entre otros
14. VTOL le responde al POS con el isocode 718 y el responseMessage “Confirma la tarjeta recibida”.
15. El POS le envía a VTOL la tercera QueryWallet con el "campo 6: cardNumber" en donde se deben ingresar los cuatro últimos dígitos de la tarjeta para confirma el pago.
16. VTOL se comunica con Gocuotas mediante el endpoint / payments. Se valida que se excede el tiempo determinado de 2 minutos para realizar el pago.
17. GoCuotas responde "Response message: (confirmed: false....)"
18. VTOL responde al POS "Response message: Error 604, No se puede realizar el pago, reinicie la operación"
19. Se reitera nuevamente el envío de una orden de venta (transacción SaleWallet) por parte del POS a VTOL.
20. VTOL se comunica con GoCuotas mediante el endpoint / send_code, en donde se envían los datos del email, dni, area_code (sin "0"), telephone_number (sin "15"), amount_in_cents, number_of_installments, order_reference_id y Authorization: Bearer.
21. GoCuotas responde a VTOL con el Message HTTP 200 (verificar cód de respuesta) y el dato del "sale_token".
22. VTOL le responde al POS el isocode 714 y el responseMessage “Orden creada, ingrese el código de verificación”
23. El POS le envía a VTOL la cuarta QueryWallet con el campo 279: softToken.
24. VTOL se comunica con GoCuotas mediante el enpoint “code_verification”, en donde le envía los campos sale_token, code y Authorization: Bearer.
25. El POS le envía a VTOL la quinta QueryWallet enviando el campo 6: cardNumber con los últimos cuatro dígitos de la tarjeta para confirmar el pago.
26. VTOL se comunica con Gocuotas mediante al endpoint / payments.
27. GoCuotas responde a VTOL con el status aprobado de la transacción y otros datos.
28. VTOL le responde a POS con el estado de la transacción aprobada (isoCode "00" y responseMessage "Aprobada")
29. Por último, el POS envía el tercer mensaje de “Commit”.

Definición del 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: si la devolución es por el monto total de la compra, se deberá enviar en el campo 12 el importe total. 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 el endpoint / orders para consultar la orden, en donde se envía el saleToken y el Authorization: Bearer.
3. GoCuotas responde el código HTTP 200 con el status de la transacción de compra y los datos de la operación.
4. VTOL le responde al POS.
5. VTOL se comunica con GoCuotas mediante el endpoint / refund para solicitar la devolución total o parcial de una venta. Se envían los parámetros sale_token y el amount_in_cents.
6. GoCuotas le responde a VTOL con datos de la transacción del refundWallet. Si la devolución se realiza por el monto total de la compra, entonces en el campo status aparece “denied”. Si el monto es menor que el importe total de la compra entonces aparece “Approved”.

Definición del flujo de la operación QueryWallet:

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 / orders, en donde se envía el saleToken y el Authorization: Bearer. 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 responde con el código HTTP 200 y con el status de la solicitud del QueryWallet de la transacción de compra.
4. VTOL le responde al POS el estado Aprobada de la operación solicitada (saleWallet o refundWallet).

1.4.29.1 Requerimiento POS - VTOL

1.4.29.2 Respuesta VTOL - POS

Âncora
_Toc485222740 _Toc485222740

1.5 Códigos de Respuesta al POS

La respuesta que el POS recibe de VTOL se encuentra en los siguientes campos:

1. Campo 27: Código de Respuesta
2. Campo 28: Descripción de la Respuesta

A continuación se detallan las respuestas posibles con una breve descripción de cada una:

...

Âncora
Códigos de respuesta VTOL Server para GoCuotas Códigos de respuesta VTOL Server para GoCuotas

1.5.4.2 Códigos de respuesta de VTOL Server para Billetera GoCuotas

A continuación, se detallan las respuestas posibles de VTOL Server, cuando se opera con GoCuotas:

Âncora
codrespnopresencial codrespnopresencial

1.5.5 Códigos de Respuesta de VTOL Server para operaciones no presenciales

...