NAV
shell

Introducción

Esta API permite a un tercero como un comercio, crear solicitudes de pago así como conocer el estado de las transacciones de pago efectuadas por los usuarios de la Billetera, con el fin de integrar este medio de pago con su flujo de negocio para la entrega de un producto y/o servicio.

Vale la pena mencionar que integrarse con Payments API permite al comercio ofrecer a sus clientes la Billetera como medio de pago dentro de ella (modalidad de miniapp o webview dentro de la Billetera) y/o fuera de la misma, como en el caso de una página web transaccional (ecommerce).

En el caso de que la aplicación web del Comercio sea embebida dentro de la Billetera (miniapp) el usuario deberá hacer su pago dando clic en un botón asociado al enlace de pago generado con el consumo del API. Si por lo contrario, la aplicación web del comercio no estará embebida dentro de la Billetera, aplicará la lógica definida al final de la descripción del endpoint de creación de una orden de pago.

Guía rápida - Modalidad miniapp (webview)

La api de miniapps permite a un comercio incluir su tienda virtual dentro de la Billetera Tpaga. En este modelo, la aplicación web del comercio es configurada como un producto y/o servicio (PYOS) de la billetera, permitiendo que el flujo inicie dentro de Tpaga.

La integración actual contempla:

  1. Rutas transaccionales para solicitud de pago.
  2. Rutas de autenticación de miniapp.
  3. Rutas de identificación/consulta de usuarios.
  4. Rutas administrativos para alta y actualización de miniapps.

La plataforma de miniapps permite a un comercio incluir su tienda virtual dentro de la aplicación Billetera Tpaga; es decir, la aplicación web del comercio es configurada como un producto y/o servicio (PYOS) de la Billetera Tpaga, permitiendo que todo el proceso inicie dentro de ésta.

El proceso de compra usando las miniapps se realiza en el siguiente orden:

Diagrama de flujo de pago por medio de miniapps Tpaga:

Un flujo típico de miniapp consiste en:

  1. El comprador abre el PYOS en la Billetera Tpaga.
  2. El comercio identifica al usuario (user_info) y obtiene su mauid cuando aplica.
  3. El comercio crea la solicitud de pago (create).
  4. Tpaga entrega el tpaga_payment_url. (debe ser consumido désde un dispositivo movil)
  5. El comprador paga en el widget de la billetera.
  6. El comercio consulta el estado (info) de manera asíncrona.
  7. El comercio ejecuta acciones de negocio (refund, cancel) según estado.

Flujo estándar

La plataforma de miniapps permite a un comercio incluir su tienda virtual dentro de la aplicación Billetera Tpaga. El flujo típico inicia en la miniapp, continúa con la creación de la solicitud de pago y finaliza con la confirmación del estado vía consulta o webhook.

Requisitos técnicos

  1. Todas las llamadas de comercio se autentican con Bearer.
  2. Si la miniapp está configurada con requires_miniapp_user=true, miniapp_user_token es obligatorio al crear la solicitud.
  3. El token payment_request_token debe ser persistido por el comercio, pues se usa para consultar, cancelar o revertir.
  4. El control de idempotencia se realiza con idempotency_token.

Estados de una solicitud de pago

API

Listado de endpoints

URL Base

Ambiente staging: - https://stag.wallet.tpaga.co/merchants/api/v1

Ambiente producción: - https://prod.wallet.tpaga.co/merchants/api/v1

Autenticación

Cada petición del comercio debe incluir autenticación.

Autenticación Bearer

Se obtiene token con POST /login_miniapp:

Petición:

curl -X POST \
https://stag.wallet.tpaga.co/merchants/api/v1/login_miniapp \
-H 'Content-Type: application/json' \
-d '{
  "miniapp_token":"mi-miniapp",
  "api_key":"mi-api-key"
}'

Respuesta:

{
  "token": "jwt-token"
}

Parámetros del body:

Parámetros de respuesta:

Uso posterior:

curl --header "Authorization: Bearer jwt-token" \
https://stag.wallet.tpaga.co/merchants/api/v1/payment_requests/create

Notas:

Consultar información de usuario

Permite consultar información básica del usuario de miniapp.

Ejemplo:

curl -X GET \
https://stag.wallet.tpaga.co/merchants/api/v1/payment_requests/users/mauid-xxxxxxxx/info \
-H 'Authorization: Bearer <jwt-token>' \
-H 'Content-Type: application/json'

Respuesta esperada:

{
  "first_name":"Nombre",
  "last_name":"Apellido",
  "phone_number":"+573001112233",
  "email":"usuario@correo.com",
  "identification_type":"CC",
  "identification_number":"1234567890",
  "additional_data": {}
}

Parámetros:

Encabezados requeridos:

Notas:

Petición de billetera 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.

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

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 solicitud de pago

Ejemplo de petición:

curl -X POST \
https://stag.wallet.tpaga.co/merchants/api/v1/payment_requests/create \
-H 'Authorization: Bearer <jwt-token>' \
-H 'Content-Type: application/json' \
-d '{
  "miniapp_user_token":"mauid-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "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":"2027-11-05T20:10:57.549653+00:00"
}'

Respuesta exitosa:

{
  "miniapp_user_token": "mauid-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "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-xxxxxxxx",
  "tpaga_payment_url": "https://w.tpaga.co/...",
  "status": "created",
  "expires_at": "2027-11-05T15:10:57.549-05:00",
  "cancelled_at": null,
  "checked_by_merchant_at": null,
  "delivery_notification_at": null
}

Parámetros:

Encabezados requeridos:

Respuestas y códigos:

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.

Nota de implementación

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

Consultar estado de la solicitud

Ejemplo de consulta:

curl -X GET \
https://stag.wallet.tpaga.co/merchants/api/v1/payment_requests/pr-xxxxxxxx/info \
-H 'Authorization: Bearer <jwt-token>' \
-H 'Content-Type: application/json'

Este endpoint devuelve la solicitud con su status actualizado.

Recomendación: consumir de forma asíncrona con reintentos controlados.

Parámetros:

Encabezados requeridos:

Respuestas típicas:

Revertir pago

Ejemplo:

curl -X POST \
https://stag.wallet.tpaga.co/merchants/api/v1/payment_requests/refund \
-H 'Authorization: Bearer <jwt-token>' \
-H 'Content-Type: application/json' \
-d '{
  "payment_request_token":"pr-xxxxxxxx"
}'

Si la petición es exitosa, el status queda en reverted.

Parámetros:

Encabezados requeridos:

Respuestas típicas:

Cancelar solicitud

Ejemplo:

curl -X POST \
https://stag.wallet.tpaga.co/merchants/api/v1/payment_requests/cancel \
-H 'Authorization: Bearer <jwt-token>' \
-H 'Content-Type: application/json' \
-d '{
  "payment_request_token":"pr-xxxxxxxx"
}'

Si la petición es exitosa, el status queda en cancelled.

Parámetros:

Encabezados requeridos:

Respuestas típicas:

Manejo recomendado de errores

La API puede responder errores de validación, negocio, autenticación o errores inesperados.

Estructura común en errores de validación (422):

{
  "error_code": 1,
  "error_message": "Input error: ...",
  "field_name": "campo",
  "rejected_value": "valor"
}

Estructura común en errores de negocio (409):

{
  "error_code": 4,
  "error_message": "Business error: ...",
  "data": {
    "token": "pr-...",
    "status": "..."
  }
}

Recomendaciones:

Webhook de confirmación

El webhook de confirmación, notifica al comercio el token de la orden de pago que ha sido exitosamente pagada por el usuario. Es decir, notifica, a un endpoint provisto por el comercio, las transacciones en estado delivered, de la siguiente manera: POST https://www.comercio.com/{payment_request_token}

Una vez recibida la petición enviada por la plataforma de pagos, el comercio podrá continuar su proceso de negocio siempre que su plataforma haya confirmado la recepción del webhook de confirmación con un mensaje 200-OK. En caso de que no se obtenga una respuesta 200-OK de parte del comercio, la plataforma de pagos hará intentos posteriores, acumulando un máximo de diez (10) peticiones dentro de las siguientes horas a la transacción. Si al cabo de los reintentos no se logra comunicación satisfactoria con el comercio, la plataforma dejará de notificar al comercio el resultado de esa transacción.

IMPORTANTE:

Notas adicionales

Entrega implícita

  1. El comercio consulta GET /payment_requests/{payment_request_token}/info.
  2. Si el pago está en estado pagado, Wallet marca la compra como entregada automáticamente.

Ejemplos de respuesta con errores por endpoint

Esta sección agrega ejemplos de errores frecuentes para facilitar pruebas de integración y homologación.

Login

401 Credenciales inválidas

POST /login_miniapp 401 Credenciales inválidas

{
  "error_code": 6,
  "error_message": "Unauthorized error: Invalid minapp token or api key"
}

401 Token Bearer expirado (al usar endpoints protegidos)

POST /login_miniapp

{
  "error_code": 6,
  "error_message": "Unauthorized error: Token has expired."
}

Crear solicitud de pago

422 cost inválido (con decimales)

POST /payment_requests/create

{
  "error_code": 1,
  "error_message": "Input error: must be an integer",
  "field_name": "cost",
  "rejected_value": "12000.10"
}

422 expires_at en pasado

POST /payment_requests/create

{
  "error_code": 1,
  "error_message": "Input error: expiration date cannot be in the past.",
  "field_name": "expires_at",
  "rejected_value": "2020-01-01T00:00:00+00:00"
}

409 idempotencia

POST /payment_requests/create

{
  "error_code": 3,
  "error_message": "Idempotency error: The payment request was already created",
  "data": {
    "token": "pr-xxxxxxxx",
    "status": "created"
  }
}

Consultar solicitud de pago

422 Token inválido

GET /payment_requests/:payment_request_token/info

{
  "error_code": 1,
  "error_message": "Input error: payment request not found.",
  "field_name": "payment_request_token",
  "rejected_value": "pr-token-invalido"
}

409 conflicto de negocio

GET /payment_requests/:payment_request_token/info

{
  "error_code": 4,
  "error_message": "Business error: payment request could not be paid.",
  "data": {
    "token": "pr-xxxxxxxx",
    "status": "charge_failed"
  }
}

Reversar solicitud de pago

422 Token inexistente

POST /payment_requests/refund

{
  "error_code": 1,
  "error_message": "Input error: payment request not found.",
  "field_name": "payment_request_token",
  "rejected_value": "pr-inexistente"
}

409 estado no reversible

POST /payment_requests/refund

{
  "error_code": 4,
  "error_message": "Business error: payment request can't be reverted.",
  "data": {
    "token": "pr-xxxxxxxx",
    "status": "created"
  }
}

Cancelar solicitud de pago

422 Token vacío

POST /payment_requests/cancel

{
  "error_code": 1,
  "error_message": "Input error: can't be blank",
  "field_name": "payment_request_token",
  "rejected_value": ""
}

409 estado no cancelable

POST /payment_requests/cancel

{
  "error_code": 4,
  "error_message": "Business error: payment request can't be cancelled.",
  "data": {
    "token": "pr-xxxxxxxx",
    "status": "delivered"
  }
}

Consultar usuario

403 Miniapp sin permiso de datos personales

GET /payment_requests/users/:tpaga_user_token/info

{
  "error_code": 7,
  "error_message": "Forbidden error: You are not allowed to see user info, please contact support."
}

422 Token no asociado a la miniapp

GET /payment_requests/users/:tpaga_user_token/info

{
  "error_code": 1,
  "error_message": "Input error: cannot obtain user info from miniapp.",
  "field_name": "tpaga_user_token",
  "rejected_value": "mauid-ajeno"
}

Recomendaciones para salida a producción

Antes de salir a productivo, validar:

  1. Manejo de 401, 403, 409, 422 y 5xx.
  2. Persistencia de idempotency_token y payment_request_token.
  3. Reintentos asíncronos sobre info para estados transitorios.
  4. Política clara de cancelación/reversión en el negocio del comercio.
  5. Rotación de API keys y uso de login_miniapp para sesiones Bearer.
  6. Monitoreo/alertamiento de errores por endpoint.

Glosario

Billetera Tpaga

Aplicación móvil de ingresos y pagos. Es la primera aplicación móvil que permite tanquear, mercar, recargar y comprar en establecimientos, desde un mismo canal que se encuentra en el celular.

Comercio

La empresa que realiza la integración con la Billetera Tpaga.

MiniApp

Aplicación web de un comercio que se abre embebida dentro de la Billetera Tpaga.

Comprador

El usuario de la Billetera Tpaga que está realizando la compra en el Comercio.

Una URL que sirve para abrir un widget de pago dentro de la Billetera Tpaga. Contiene información provista por el Comercio como el precio y la descripción de la compra.

Una URL provista por el Comercio que se abre justo después de que el Comprador finalice el pago dentro de la Billetera Tpaga.

Una URL provista por el Comercio que sirve como referencia que aparece en el historial de pagos dentro de la Billetera Tpaga y lleva a una página del Comercio con los detalles de la compra. Puede ser enlace a la página con el comprobante de pago/voucher, que el Comercio le presenta al Comprador, en su página web. Es opcional.

Solicitud de pago

El registro dentro de la Tpaga API que corresponde a una compra en el Comercio. La solicitud de pago contiene la información del valor, la descripción de la compra, el número de orden y otros datos, provistos por el Comercio, y el estado de pago, realizado por el Comprador.

Token de idempotencia

El identificador de la transacción, que sirve para evitar la creación de solicitudes de pago duplicadas dentro de la Tpaga API. Cuando el Comercio trata de crear una nueva solicitud de pago con un token de idempotencia que ya se haya utilizado anteriormente, la petición de no se completará y generará una respuesta con un error 409: Solicitud de pago ya existe. Mediante este campo evitamos cobros múltiples por error.

Tpaga API

Interfaces de programación de aplicaciones de Tpaga. La Tpaga API sirve para establecer la comunicación entre el sistema del comercio y la Billetera Tpaga.

shell