Tilopay Banking API

Tilopay's Banking API lets an integrated client initiate payments (PIN and SINPE Móvil), check their status, manage accounts and subscribe to payment event webhooks, always limited to the accounts the access token authorizes.

It is a separate product from the payment gateway. It runs on its own infrastructure, with its own host, credentials and authentication. A merchant already integrated with the acquiring API does not get access to this one automatically.

This reference is generated from the Banking API OpenAPI 3.0.3 spec, version 1.0.0.

What it can do#

Payments. Create a payment, fetch it by identifier, list it by account and search it by payment_id, public_id or client_reference; the declared methods are PIN and SINPE_MOVIL, in OUT or IN direction. See payment operations.

Accounts. Validate a destination account before transferring, list accessible accounts with or without balances, check an account balance and request statements asynchronously. See account operations.

Webhooks. Register an encrypted HTTPS destination, list the features you can subscribe to per payment method and fetch each event's payload contract. See webhook operations.

Catalogs. Customer identification person types per country. See catalogs.

The API also exposes GET /api/public/v1/healthz for health checks, plus GET /openapi.yaml and GET /docs for the raw spec and the host's own documentation UI.

Platform capabilities outside public API v1#

Tilopay's banking platform offers commercial capabilities that public API v1 does not declare: DTR transfers, VISA or Mastercard card issuing and collections management. There are no operations for them in this version of the API; to evaluate them, write to soporte@tilopay.com.

Environments#

The spec declares a single server, the sandbox one:

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

The production host and each environment's credentials are handed over when access is enabled. Routes and contracts are the same in both environments.

Machine-readable artifacts#

The full spec is served, with open CORS, in two formats:

• openapi.json
• openapi.yaml

It is a different artifact from the acquiring API spec (/developers/openapi.json): they are two separate APIs.

How to get access#

Access is restricted and granted on request, for operations in Costa Rica. To learn about the product and request it: baas.tilopay.com, stating estimated monthly volume, use case and systems to integrate.

Where to go next#

1. Authentication — login, token exchange and Bearer.
2. Conventions — envelope, correlation, safe retries, pagination and dates.
3. Response codes — full response_code catalog.