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:

Diagrama de flujo

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

URL Base

Ambiente staging:

Ambiente producción:

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.

Parámetros:

Encabezados requeridos:

Notas:

Sin include_audit_data

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:

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

Con include_audit_data=true

Ejemplo:

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

Respuesta:

{
  "first_name": "Nombre",
  "last_name": "Apellido",
  "phone_number": "+573001112233",
  "email": "usuario@correo.com",
  "identification_type": "CC",
  "identification_number": "1234567890",
  "additional_data": {},
  "audit_data": {
    "vendor": "Samsung",
    "model": "SM-G991B",
    "os_name": "Android",
    "os_version": "14",
    "user_agent_string": null,
    "lonlat": "4.710989,-74.072092",
    "account_number": "1234567890",
    "office": "001",
    "token": "mauid-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "uuid": null,
    "ip": null,
    "sim_operator": null,
    "mac": null,
    "serial_device": null,
    "sim_device_id": null,
    "sim_cell_number": null,
    "sim_serial_number": null
  }
}

Campos de audit_data (todas las llaves se retornan; valores no disponibles o no expuestos van en null):

Campo Descripción
vendor Fabricante del dispositivo (devices.vendor).
model Modelo del dispositivo.
os_name Nombre del sistema operativo.
os_version Versión del sistema operativo.
user_agent_string Siempre null (no lo persiste la app).
lonlat Últimas coordenadas de login en los últimos 10 días, formato "lat,lon".
account_number Número de la cuenta Coopcentral más reciente del usuario.
office Código de oficina Coopcentral (configuración COOPCENTRAL_AUDIT_DATA_OFFICE).
token Token del usuario de miniapp (MAUID).
uuid Siempre null.
ip Siempre null.
sim_operator Siempre null.
mac Siempre null.
serial_device Siempre null.
sim_device_id Siempre null.
sim_cell_number Siempre null.
sim_serial_number Siempre null.

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:

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

Listado de endpoints

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

{
  "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.

Manejo OAuth en Miniapps que usan APIs de Punto Red

Algunas miniapps embebidas requieren autenticarse ante APIs de Punto Red. En este escenario, Tpaga Wallet actua como intermediario y entrega a la miniapp un token de acceso listo para uso (auth_token), sin exponer credenciales sensibles del comercio.

Alcance

Esta funcionalidad aplica solo para miniapps configuradas con autorizacion requerida. Si la miniapp no requiere autorizacion, la respuesta mantiene el flujo base sin campos OAuth adicionales.

Responsabilidades

Flujo funcional (alto nivel)

  1. El usuario autenticado abre la miniapp en Wallet.
  2. Wallet solicita la informacion de sesion de miniapp.
  3. Si la miniapp tiene autorizacion requerida, Wallet incluye auth_token en la respuesta.
  4. La miniapp usa ese token para consumir APIs de Punto Red.
  5. Si corresponde, Wallet indica envio via postMessage con event_PostMessage.

Respuesta esperada al abrir miniapp

Respuesta base:

{
  "tpagaMiniappUserId": "string",
  "miniappUrl": "string"
}

Campos adicionales cuando aplica autorizacion:

{
  "auth_token": "string",
  "auth_type": "Bearer",
  "event_PostMessage": true
}

Descripcion de campos OAuth:

Uso del token en requests a Punto Red

Authorization: Bearer <auth_token>

Buenas practicas:

Errores funcionales para el cliente

Si no es posible generar credenciales, el flujo puede responder con error HTTP y mensaje de negocio:

No fue posible generar las credenciales de autenticacion de la miniapp.

Recomendaciones:

Checklist para habilitacion (cliente)

Seguridad

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