Tilopay for developers
Everything you need to take payments with Tilopay: four integration paths, the field contract, the SDK reference and webhooks.
Step 0 — get your sandbox credentials
There are no shared sandbox credentials: every developer registers and receives their own. Do this before any of the four paths.
Register as a developerTilopay AI tools
Tilopay has AI tools for two different audiences. For the developer who is integrating, the debugging agent. For other AI agents that consume or operate Tilopay, the MCP server and the machine-readable artifacts.
Debugging agent
Understand why a call failed, what a response code means, whether your request has the right shape according to the spec, and where the answer is documented — without leaving the page you are reading. It cites the page behind every answer, never runs calls against the API and never accepts credentials.
Open it from the side panel of any portal page.
MCP server
Connect an assistant to the merchant account — sales, payment links, refunds — without the merchant ever pasting its API credentials.
MCP server →Machine-readable documentation
llms.txt, the .md version of any URL, openapi.json and mcp.json, so an agent can read the portal without scraping HTML.
Machine-readable documentation →For developers
Four integration paths
No code
Extensions and plugins for existing platforms. The merchant does not write a line of code.
See path →Hosted payment page
Your server requests a URL from the API, redirects the customer to that Tilopay page and receives the result on your callback URL.
See path →JavaScript SDK
The card fields live in your page; the SDK captures them and sends them straight to Tilopay.
See path →Server-to-server API
Restricted access: a service exclusive to PCI-certified merchants. The URL is provisioned per merchant and is not public.
Requirements and request →How to choose
Choosing the wrong path is expensive. The difference that matters most is where the card data travels.
| Path | Who builds the form | Where card data travels | What you need to know | Compliance implication |
|---|---|---|---|---|
| 1 · No code | The platform | Never pass through the merchant | Setup inside the platform admin | Check with your compliance team |
| 2 · Hosted payment page | Tilopay | The customer leaves the merchant site and types them on a Tilopay page; the merchant never sees a card number | Backend: request the URL and handle the callback | Check with your compliance team |
| 3 · JavaScript SDK | The merchant | Typed on the merchant page but sent from the browser straight to Tilopay; they do not pass through the merchant server | JavaScript frontend, plus backend for credentials | Check with your compliance team |
| 4 · Server-to-server (restricted access) | The merchant | Card data passes through the merchant server | Requires merchant PCI certification and a URL provisioned by Tilopay | Check with your compliance team |
Path 4 is not self-serve: it is exclusive to merchants holding PCI certification, and the URL is provisioned individually. It is also the only path that puts the merchant server inside PCI DSS scope. Paths 2 and 3 avoid that cost and you can start them today.
Tilopay Banking API
A separate product, not a fifth integration path: a Banking-as-a-Service platform with SINPE transfers, IBAN accounts and collections, available in Costa Rica only, on its own infrastructure and with its own credentials.
See the Banking API →Machine-readable spec
OpenAPI 3.1 spec for the Tilopay API: the source of truth for endpoints, parameters and responses. Use it to generate a client or import the API into your tooling.