API Bancario de Tilopay

Con nuestro API Bancario podés iniciar pagos (PIN y SINPE Móvil), consultar su estado, administrar tus cuentas y recibir webhooks de eventos de pago desde tus propios sistemas, siempre limitado a las cuentas que autoriza tu token de acceso.

Es un producto separado de la pasarela de pagos. Corre en su propia infraestructura, con host, credenciales y autenticación propias. Si ya integrás nuestro API de adquirencia, el acceso a este se habilita por separado.

En esta documentación encontrás los endpoints, modelos y flujos oficiales de la versión 1.0.0 del API Bancario.

Qué permite hacer#

Pagos. Creá un pago, consultalo por identificador, listalo por cuenta y buscalo por payment_id, public_id o client_reference; los métodos disponibles son PIN y SINPE_MOVIL. La creación solo admite dirección OUT; los pagos IN siguen en listados y webhooks. Ver operaciones de pagos.

Cuentas. Validá una cuenta destino antes de transferir, listá tus cuentas con o sin saldos, consultá el saldo de una cuenta y solicitá estados de cuenta de forma asincrónica. Ver operaciones de cuentas.

Webhooks. Registrá tu destino HTTPS cifrado, consultá los eventos a los que podés suscribirte por método de pago y la estructura de datos que te enviamos en cada uno. Ver operaciones de webhooks.

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

Además, ponemos a tu disposición GET /api/public/v1/healthz para chequeo de salud, y GET /openapi.yaml y GET /docs con la definición OpenAPI y la documentación interactiva directamente en el host del API.

Entornos#

Hay dos entornos, con las mismas rutas y contratos. El de pruebas:

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

El de producción es el mismo host sin el sufijo -sandbox:

https://api-baas.tilopay.com

Tilopay emite las credenciales de prueba a solicitud; coordiná el acceso con el contacto de tu comercio en Tilopay. Cuando estés listo, te entregamos las credenciales de producción al habilitar tu acceso.

Artefactos legibles por máquina#

Publicamos la definición OpenAPI completa del API Bancario, con CORS abierto, en dos formatos:

• openapi.json
• openapi.yaml

Es independiente de la definición de nuestro API de adquirencia (/developers/openapi.json): son dos productos separados.

Cómo obtener acceso#

El acceso es restringido y se otorga por solicitud, para operaciones en Costa Rica. Para conocer el producto y solicitarlo, visitá 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.