Guía de Inicio Rápido¶

La compra de un producto y/o servicio desde una miniapp consiste en los siguientes pasos:

El Comprador abre el producto y/o el servicio (PYOS) dentro de la Billetera Tpaga.
La Billetera Tpaga abre un Webview en el que muestra al Comprador la aplicación Web del Comercio. Para más detalle, puede ver la opción Petición de billetera al comercio
El Comprador interactua con la aplicación Web del Comercio
El Comprador crea una solicitud de pago al Comercio
El Comercio crea una Solicitud de pago asociado al Comprador en la Tpaga API por el valor que debe ser cancelado.
La Tpaga API devuelve un Link de pago al Comercio.
El Comercio pasa el link de pago al Comprador, quien debe realizar el pago.
El Comprador recibe el link de pago y lo abre en su dispositivo móvil. Al hacerlo, se le abre automáticamente Billetera Tpaga y aparece un widget que lo invita a realizar el pago.
El Comprador realiza el pago dentro de la Billetera Tpaga.
La Billetera Tpaga redirige al Comprador al Link de finalización de compra.
El Comercio hace una petición a la Tpaga API para confirmar el estado de pago.
Si el pago fue exitoso, el Comercio entrega el producto/servicio al Comprador, y le notifica a Tpaga que hizo la entrega al Comprador.

Aspectos importantes de las miniapps.¶

Las miniapps se abren solamente desde el PYOS configurado en la billetera, y recibe token del comprador como parámetro en la petición GET realizada.
A diferencia de los links de pago, el token del comprador debe es un campo obligatorio al momento de crear la solicitud de pago.
Es recomendable que las miniapps implementen que el UserAgent de cada petición realizada en el flujo de pagos contenga la cadena «Tpaga», ya que esto ayuda a tener una mejor depuración sobre por dónde fue abierta la miniapp (dentro la billetera -por el UserAgent- o desde otro navegador).

Miremos con más detalle algunos pasos del proceso:

Autenticación contra la Tpaga API.¶

Cada petición que el Comercio envía a Tpaga API debe tener el encabezado de la autenticación de acceso básica (Basic Authentication), que es basado en nombre de usuario y contraseña asignados al Comercio por Tpaga y están codificados en Base64.

Por ejemplo, si el nombre de usuario del Comercio es tiendaX y la contraseña es 123456, esos datos se concatenan en la siguiente cadena: tiendaX:123456, se codifican en Base64: dGllbmRhWDoxMjM0NTY= y se envían dentro del encabezado Authorization:

curl --header "Authorization: Basic dGllbmRhWDoxMjM0NTY=" https://stag.wallet.tpaga.co/merchants/api/v1/

Petición de billtera al comercio¶

Una vez fue abierto el PYOS dentro de la Billetera Tpaga, esta abre un Webview que realiza una petición de tipo GET a la aplicación Web del comercio con el parámetro tpagaMiniappUserId, cuyo valor es el token del comprador, Esto con el fin que el comercio tenga relacionado al usuario que desea interactuar con su aplicación.

GET https://url-de-comercio.co?tpagaMiniappUserId=4661b7ff-ae16-441a-9a44-49b750f2b9b6

A continuación, se muestra un ejemplo sobre lo que puede abrir el webview de la miniapp.

Es recomendable que el comercio en su aplicación mantenga el flujo lo más sencillo posible, el objetivo es que el usuario pueda llegar a efectuar el pago tan pronto como sea posible, por ejemplo, añadiendo items a un carrito de compra dentro de la miniapp o eligiendo con facilidad aquello por lo que desea pagar. Una vez el cliente ha elegido todo aquello por lo que desea pagar, el comercio esta listo para Crear la solicitud de pago.

Crear la solicitud de pago.¶

Para crear una Solicitud de pago se debe hacer una petición POST a la Tpaga API desde el servidor del comercio, no desde el navegador o webview. Los parámetros que debe tener esta petición son los siguientes:

miniapp_user_token - token del comprador, entregado al momento que éste abre el pyos desde la Billetera Tpaga
cost - valor total de la compra;
purchase_details_url - el Link de finalización de compra. Esta es la página en el sitio web del comercio a la cual la Billetera Tpaga enviará al Comprador una vez se haya hecho el cobro, para continuar/terminar el proceso de compra.
voucher_url - el Link de detalle de compra (opcional);
idempotency_token - el Token de idempotencia, que es un identificador de la transacción, que sirve para evitar la creación de solicitudes de pago duplicadas dentro de la Tpaga API;
order_id - el identificador de la compra dentro del sistema de inventario del Comercio, por ejemplo, el número de factura (no es necesario que sea único). Sirve para que el comercio pueda hacer conciliación de sus compras.
terminal_id - el identificador, definido por el Comercio, por ejemplo, número de la caja o nombre de la sede, en la que se realizó la compra. Sirve para hacer mejor seguimiento de las compras;
purchase_description - la descripción de la compra; la Billetera le mostrará al Comprador este texto al momento de cobrarle, para comunicarle mejor qué está pagando y a quién lo hace. Por ejemplo : Pago de Servicio a Comercio X.
purchase_items - Una estructura json que le va a ayudar al comercio a saber con exactitud todo lo que está pagando (opcional);
user_ip_address - la dirección IP del Comprador (si existe) o de la máquina, que está haciendo la petición;
expires_at - la fecha y la hora en la que se expira el Link de pago (en el formato ISO 8601, por ejemplo 2018-11-05T15:10:57.549-05:00). Después de la fecha indicada el link de pago se expira, y no está disponible para pagar.

El ejemplo de una petición para crear una solictud de pago, sería:

curl -X POST \
https://stag.wallet.tpaga.co/merchants/api/v1/payment_requests/create \
-H 'Authorization: Basic bWluaWFwcG1hLW1pbmltYWw6YWJjMTIz' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"miniapp_user_token": "4661b7ff-ae16-441a-9a44-49b750f2b9b6",
"cost":"12000",
"purchase_details_url":"https://example.com/compra/348820",
"voucher_url":"https://example.com/comprobante/348820",
"idempotency_token":"ea0c78c5-e85a-48c4-b7f9-24a9014a2339",
"order_id":"348820",
"terminal_id":"sede_45",
"purchase_description":"Compra en Tienda X",
"purchase_items":[
    {
        "name":"Aceite de girasol",
        "value":"13.390"
    },
    {
        "name":"Arroz X 80g",
        "value":"4.190"
    }
],
"user_ip_address":"61.1.224.56",
"expires_at":"2018-11-05T20:10:57.549653+00:00"
}'

Si la petición fue exitosa (es decir, no hubo errores en los datos enviados), la Tpaga API devuelve la siguiente respuesta:

{
    "miniapp_user_token": "4661b7ff-ae16-441a-9a44-49b750f2b9b6",
    "cost": "12000.0",
    "purchase_details_url": "https://example.com/compra/348820",
    "voucher_url": "https://example.com/comprobante/348820",
    "idempotency_token": "ea0c78c5-e85a-48c4-b7f9-24a9014a2339",
    "order_id": "348820",
    "terminal_id": "sede_45",
    "purchase_description": "Compra en Tienda X",
    "purchase_items": [
        {
            "name": "Aceite de girasol",
            "value": 13390
        },
        {
            "name": "Arroz X 80g",
            "value": 4190
        }
    ],
    "user_ip_address": "61.1.224.56",
    "merchant_user_id": null,
    "token": "pr-39394abaed1d3e97d1fe67423079c36336905671bb5a77877e3b9dc032a3070c52162365",
    "tpaga_payment_url": "https://w.tpaga.co/eyJtIjp7Im8iOiJQUiJ9LCJkIjp7InMiOiJtaW5pbWFsLW1hIiwicHJ0IjoicHItMzkzOTRhYmFlZDFkM2U5N2QxZmU2NzQyMzA3OWMzNjMzNjkwNTY3MWJiNWE3Nzg3N2UzYjlkYzAzMmEzMDcwYzUyMTYyMzY1In19",
    "status": "created",
    "expires_at": "2018-11-05T15:10:57.549-05:00",
    "cancelled_at": null,
    "checked_by_merchant_at": null,
    "delivery_notification_at": null
}

Dentro del cuerpo de la respuesta, la Tpaga API confirma los datos de la solicitud de pago y envía el Link de pago en el campo tpaga_payment_url junto con un identificador de la solicitud de pago creada - el campo token.

token es el identificador de la solicitud de pago, dentro del sistema Tpaga. Se usa para referirse a la compra al hacer peticiones a la Tpaga API (por ejemplo, para obtener información del estado de pago o para revertir de pago).

tpaga_payment_url es el link de pago al cual debe redirigir la aplicación web del comercio para que el usuario pueda pagar.

Abrir link de pago y pagar.¶

El link de pago lleva al Comprador a la aplicación Billetera Tpaga, donde se abre un widget de pago con el valor de la compra cost y la descripción purchase_description definidos por el Comercio:

Después de que el Comprador realice el pago, se actualiza el estado de la Solicitud de pago dentro de la Tpaga API - se pasa del estado created (creado) a paid (pagado). En el caso de error al momento de pagar, el estado de la solicitud de pago se cambia a failed (pago fallido).

Después de finalizar el pago en la aplicación, Tpaga Wallet cierra el widget de pago y redirige al Comprador al Link de finalización de compra en la página del Comercio. Este link purchase_details_url fue definido por el Comercio al momento de crear la solicitud de pago.

Confirmar el estado de la solicitud de pago.¶

En el momento que el Comprador llegue al Link de finalización de compra el Comercio debe confirmar con la Tpaga API el estado de la Solicitud de pago para determinar si el Comprador pudo pagar o no, antes de decidir entregar el producto.

Para esto, el sistema del Comercio debe hacer una petición al servicio de consulta de estado de pago, especificando el identificador de la solicitud de pago, que obtuvo al momento de la creación (el campo token):

curl -X GET \
https://stag.wallet.tpaga.co/merchants/api/v1/payment_requests/pr-3d6a2289193bec5adb5080dc2e91cadeba29b58f06ebbba1aba4c9eb85c6777e76811dcd/info \
-H 'Authorization: Basic bWluaWFwcG1hLW1pbmltYWw6YWJjMTIz' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

La Tpaga API devolverá los datos de la solicitud de pago con el estado (status) actualizado:

{
    "miniapp_user_token": "4661b7ff-ae16-441a-9a44-49b750f2b9b6",
    "cost": "12000.0",
    "purchase_details_url": "https://example.com/compra/348820",
    "voucher_url": "https://example.com/comprobante/348820",
    "idempotency_token": "ea0c78c5-e85a-48c4-b7f9-24a9014a2339",
    "order_id": "348820",
    "terminal_id": "sede_45",
    "purchase_description": "Compra en Tienda X",
    "purchase_items": [
        {
            "name": "Aceite de girasol",
            "value": "13.390"
        },
        {
            "name": "Arroz X 80g",
            "value": "4.190"
        }
    ],
    "user_ip_address": "61.1.224.56",
    "merchant_user_id": null,
    "token": "pr-3d6a2289193bec5adb5080dc2e91cadeba29b58f06ebbba1aba4c9eb85c6777e76811dcd",
    "tpaga_payment_url": "https://w.tpaga.co/eyJtIjp7Im8iOiJQUiJ9LCJkIjp7InMiOiJtaW5pbWFsLW1hIiwicHJ0IjoicHItM2Q2YTIyODkxOTNiZWM1YWRiNTA4MGRjMmU5MWNhZGViYTI5YjU4ZjA2ZWJiYmExYWJhNGM5ZWI4NWM2Nzc3ZTc2ODExZGNkIn19",
    "status": "paid",
    "expires_at": "2018-11-05T15:10:57.549-05:00",
    "cancelled_at": null,
    "checked_by_merchant_at": "2018-10-22T11:26:16.964-05:00",
    "delivery_notification_at": "2018-10-22T11:26:16.980-05:00"
}

En el caso del pago exitoso, el valor del campo status puede ser paid (pagado) o delivered (pagado y entregado) para el caso de entrega automática. Para entender más de entrega automática, ver sección Reportar la entrega del producto.

Reportar la entrega del producto.¶

Hay dos maneras de notificar a Tpaga que ya se entregó al Comprador el producto/servicio que compró:

Explícitamente: después del cobro exitoso, una vez el Comercio hace la entrega, el Comercio hace una petición a la Tpaga API, indicando que entregó el producto/servicio.
Implícitamente: en este modo, Tpaga asume que, una vez el Comercio se entera de que el pago fue exitoso, se puede considerar el producto/servicio como entregado.

De forma predeterminada, todos los usuarios de este API están en modo explícito; asegúrese de comunicar a Tpaga si desea usar el modo implícito, para configurar su integración de manera acorde.

El Comercio debe reportar la entrega de las compras, porque de lo contrario Tpaga devolverá el dinero a los usuarios de Billetera.

Cuando el Comercio está configurado dentro del sistema Tpaga para realizar la entrega manual, se debe llamar al servicio de la entrega:

curl -X POST \
https://stag.wallet.tpaga.co/merchants/api/v1/payment_requests/confirm_delivery \
-H 'Authorization: Basic bWluaWFwcG1hLW1pbmltYWw6YWJjMTIz' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
  "payment_request_token":"pr-3d6a2289193bec5adb5080dc2e91cadeba29b58f06ebbba1aba4c9eb85c6777e76811dcd"
}'

La Tpaga API devuelve los datos de la solicitud de pago con el estado (status) actualizado:

{
    "miniapp_user_token": "4661b7ff-ae16-441a-9a44-49b750f2b9b6",
    "cost": "12000.0",
    "purchase_details_url": "https://example.com/compra/348820",
    "voucher_url": "https://example.com/comprobante/348820",
    "idempotency_token": "ea0c78c5-e85a-48c4-b7f9-24a9014a2339",
    "order_id": "348820",
    "terminal_id": "sede_45",
    "purchase_description": "Compra en Tienda X",
    "purchase_items": [
        {
            "name": "Aceite de girasol",
            "value": "13.390"
        },
        {
            "name": "Arroz X 80g",
            "value": "4.190"
        }
    ],
    "user_ip_address": "61.1.224.56",
    "merchant_user_id": null,
    "token": "pr-3d6a2289193bec5adb5080dc2e91cadeba29b58f06ebbba1aba4c9eb85c6777e76811dcd",
    "tpaga_payment_url": "https://w.tpaga.co/eyJtIjp7Im8iOiJQUiJ9LCJkIjp7InMiOiJtaW5pbWFsLW1hIiwicHJ0IjoicHItM2Q2YTIyODkxOTNiZWM1YWRiNTA4MGRjMmU5MWNhZGViYTI5YjU4ZjA2ZWJiYmExYWJhNGM5ZWI4NWM2Nzc3ZTc2ODExZGNkIn19",
    "status": "delivered",
    "expires_at": "2018-11-05T15:10:57.549-05:00",
    "cancelled_at": null,
    "checked_by_merchant_at": "2018-10-22T11:26:16.964-05:00",
    "delivery_notification_at": "2018-10-22T11:29:36.017-05:00"
}

En el caso que la entrega sea exitosa, el campo status tendrá el valor delivered. Al Comprador le llegará una notificación por medio de la Billetera Tpaga, informando que la compra fue exitosa. En el comprobante de pago aparecerá el Link de detalle de compra - la información contenida en el campo voucher_url, especificado por el Comercio al crear la solicitud de pago.

Revertir el pago.¶

Tpaga ofrece el servicio de realizar una devolución de dinero al Comprador.

Para solicitar una devolución se debe enviar una petición a la Tpaga API con el identificador de la solicitud de pago, cuyo valor hay que reembolsar:

curl -X POST \
https://stag.wallet.tpaga.co/merchants/api/v1/payment_requests/refund \
-H 'Authorization: Basic bWluaWFwcG1hLW1pbmltYWw6YWJjMTIz' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
  "payment_request_token":"pr-3d6a2289193bec5adb5080dc2e91cadeba29b58f06ebbba1aba4c9eb85c6777e76811dcd"
}'

La Tpaga API devuelve los datos de la solicitud de pago con el estado (status) actualizado:

{
    "miniapp_user_token": "4661b7ff-ae16-441a-9a44-49b750f2b9b6",
    "cost": "12000.0",
    "purchase_details_url": "https://example.com/compra/348820",
    "voucher_url": "https://example.com/comprobante/348820",
    "idempotency_token": "ea0c78c5-e85a-48c4-b7f9-24a9014a2339",
    "order_id": "348820",
    "terminal_id": "sede_45",
    "purchase_description": "Compra en Tienda X",
    "purchase_items": [
        {
            "name": "Aceite de girasol",
            "value": "13.390"
        },
        {
            "name": "Arroz X 80g",
            "value": "4.190"
        }
    ],
    "user_ip_address": "61.1.224.56",
    "merchant_user_id": null,
    "token": "pr-3d6a2289193bec5adb5080dc2e91cadeba29b58f06ebbba1aba4c9eb85c6777e76811dcd",
    "tpaga_payment_url": "https://w.tpaga.co/eyJtIjp7Im8iOiJQUiJ9LCJkIjp7InMiOiJtaW5pbWFsLW1hIiwicHJ0IjoicHItM2Q2YTIyODkxOTNiZWM1YWRiNTA4MGRjMmU5MWNhZGViYTI5YjU4ZjA2ZWJiYmExYWJhNGM5ZWI4NWM2Nzc3ZTc2ODExZGNkIn19",
    "status": "reverted",
    "expires_at": "2018-11-05T15:10:57.549-05:00",
    "cancelled_at": null,
    "checked_by_merchant_at": "2018-10-22T11:26:16.964-05:00",
    "delivery_notification_at": "2018-10-22T11:29:36.017-05:00"
}

En el caso que el reembolso sea exitoso, el campo status tendrá el valor reverted (pago revertido). Al Comprador le llegará una notificación por medio de la Billetera Tpaga, informado que el pago ha sido revertido.

Posibles estados para una solicitud de pago.¶

created: solicitud de pago creada y disponible para pagar.
paid: pagada por el Comprador.
failed: el pago no fue exitoso.
expired: solicitud de pago se expiró y no está disponible para pagar.
delivered: los productos comprados fueron entregados.
reverted: el dinero fue reembolsado.