API Bancario de Tilopay

El API Bancario de Tilopay permite a un cliente integrado iniciar pagos (PIN y SINPE Móvil), consultar su estado, administrar cuentas y suscribirse a webhooks de eventos de pago, siempre limitado a las cuentas que autoriza el token de acceso.

Es un producto separado de la pasarela de pagos. Corre en su propia infraestructura, con host, credenciales y autenticación propias. Un comercio que ya integra el API de adquirencia no obtiene acceso a este automáticamente.

Esta referencia se genera desde el spec OpenAPI 3.0.3 del API Bancario, versión 1.0.0.

Qué permite hacer#

Pagos. Crear un pago, consultarlo por identificador, listarlo por cuenta y buscarlo por payment_id, public_id o client_reference; los métodos declarados son PIN y SINPE_MOVIL, en dirección OUT o IN. Ver operaciones de pagos.

Cuentas. Validar una cuenta destino antes de transferir, listar las cuentas accesibles con o sin saldos, consultar el saldo de una cuenta y solicitar estados de cuenta de forma asincrónica. Ver operaciones de cuentas.

Webhooks. Registrar un destino HTTPS cifrado, listar los features suscribibles por método de pago y consultar el contrato de payload de cada evento. Ver operaciones de webhooks.

Catálogos. Tipos de persona de identificación de cliente por país. Ver catálogos.

Además, el API expone GET /api/public/v1/healthz para chequeo de salud, y GET /openapi.yaml y GET /docs para el spec crudo y la interfaz de documentación del propio host.

Capacidades de la plataforma fuera del API público v1#

La plataforma bancaria de Tilopay ofrece capacidades comerciales que el API público v1 no declara: transferencias DTR, emisión de tarjetas VISA o Mastercard y gestión de recaudos. No hay operaciones para ellas en esta versión del API; para evaluarlas, escribí a soporte@tilopay.com.

Entornos#

El spec declara un único servidor, el de pruebas:

https://api-baas-sandbox.tilopay.com

El host de producción y las credenciales de cada entorno se entregan al habilitar el acceso. Las rutas y los contratos son los mismos en ambos entornos.

Artefactos legibles por máquina#

El spec se sirve completo, con CORS abierto, en dos formatos:

• openapi.json
• openapi.yaml

Es un artefacto distinto del spec del API de adquirencia (/developers/openapi.json): son dos APIs separadas.

Cómo obtener acceso#

El acceso es restringido y se otorga por solicitud, para operaciones en Costa Rica. Para conocer el producto y solicitarlo: baas.tilopay.com, indicando volumen mensual estimado, caso de uso y sistemas a integrar.

Por dónde seguir#

1. Autenticación — login, intercambio de token y Bearer.
2. Convenciones — envelope, correlación, reintentos seguros, paginación y fechas.
3. Códigos de respuesta — catálogo completo de response_code.