# Tilopay Developer and AI Agent Portal — full text
> Tilopay technical documentation (SDK, API, webhooks, testing) in Markdown, with nothing normative locked inside images.
Language: English. Index: https://www.tilopay.com/en/llms.txt
## Machine-readable artifacts
- [openapi.json](https://www.tilopay.com/developers/openapi.json): OpenAPI 3.1 spec of the Tilopay API, source of truth for endpoints, parameters and responses.
- [mcp.json](https://www.tilopay.com/developers/mcp.json): Catalog of the 27 tools of the Tilopay MCP server, with parameters, outputs and access level.
---
# Hosted payment page
> The integration path where the customer pays on a page hosted by Tilopay and your server receives the result.
- kind: guide
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/hosted-payment-page
## What it is [#que-es]
Your server requests a payment URL from the API, redirects the customer to that Tilopay page
and receives the result on your callback URL.
Card data is typed on a Tilopay page: **the merchant never sees a card number** and the
merchant server stays out of that flow.
The API operations for this path live in [API · Hosted payment page](/developers/api/hosted-payment-page).
## Who it is for [#para-quien]
For teams that take payments with their own code but prefer not to build or maintain the card
form. What you need is backend work: request the URL and handle the callback.
## What you need before starting [#requisitos]
1. **Your own credentials.** There are no shared sandbox credentials: every developer gets
theirs through [developer registration](/developers/registro).
2. **API authentication.** See [authentication](/developers/api/autenticacion).
3. **A callback URL of yours** that can receive the transaction result.
## How to confirm the state of a charge [#confirmacion]
The result arriving on your callback is not the only signal available, and not every error
response travels with an HTTP 4xx:
- Read [how to read an error response](/developers/api/procesos-operativos/errors) before declaring success.
- Configure [webhooks](/developers/api/webhooks) for the events you care about.
- If a call fails without a clear response, resolve the state with
[safe retries](/developers/concepts/reintentos-seguros).
## Environments [#entornos]
Testing and production share the same host. See
[environments](/developers/concepts/entornos) before taking real money.
## Compliance [#cumplimiento]
Together with the no-code path, this is the one that exposes your infrastructure the least.
Confirm the applicable scope with your compliance team.
## If you prefer the form on your own site [#alternativa]
Use the [JavaScript SDK](/developers/sdk): the design is yours and the data still does not
pass through your server.
---
# JavaScript SDK
> The integration path where the card form lives on your page and the SDK sends the data straight to Tilopay.
- kind: guide
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/sdk
## What it is [#que-es]
The card fields live on your page. The V2 SDK takes over those inputs and sends the data
**from the browser straight to Tilopay**: it never passes through your server.
## Who it is for [#para-quien]
For teams that want to control the checkout design without card data touching their backend.
You need a JavaScript frontend and a minimal backend to obtain the SDK token.
## How to build it, in order [#orden]
1. **Credentials.** There are no shared sandbox credentials: get yours through
[developer registration](/developers/registro).
2. **SDK token.** Your backend requests it with `POST /api/v1/loginSdk`. See
[authentication](/developers/api/autenticacion).
3. **Load the script.** See [installation](/developers/sdk/instalacion).
4. **Add the inputs with the contract ids** and the `responseTilopay` container. See
[form fields](/developers/sdk/campos-del-formulario).
5. **Start the purchase** with [`Tilopay.Init()`](/developers/sdk/reference/init) and show the
customer the payment methods it returns.
6. **Close the purchase** with
[`Tilopay.startPayment()`](/developers/sdk/reference/startpayment). The SDK handles 3DS and
renders the result on your `redirect` URL.
## Before assuming you are in test mode [#entornos]
Testing and production share one host: the mode is verified with the `test` field returned by
`Init()`. See [environments](/developers/concepts/entornos).
## Compliance [#cumplimiento]
Card data does not pass through your server, but your page captures it: check the applicable
scope with your compliance team.
---
# Server-to-server API (restricted access)
> A service exclusive to PCI-certified merchants. The URL is provisioned per merchant: it is not self-serve.
- kind: guide
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/server-to-server
**Restricted access. This is not a self-serve path.** You cannot start this integration on your own
today: it requires merchant PCI certification and a URL provisioned individually by Tilopay.
## What it is [#que-es]
The path where card data passes through the merchant's server, which then sends it to the Tilopay
API.
## Who it is for [#para-quien]
- It is a **service exclusive to merchants holding PCI certification**.
- The **URL is customized per merchant**, with its own key. **It is not a public URL.**
That is why this page has no endpoint, no executable examples and no request bodies: there is no
common address that works for everyone.
## Requirements [#requisitos]
1. Valid PCI certification for the merchant.
2. An active Tilopay account.
3. An approved request, with the URL and key provisioned by Tilopay for your merchant.
## How to request it [#solicitud]
Write to `sac@tilopay.com` with the merchant name and the status of your PCI certification. The URL
and key are delivered directly to the approved merchant.
## Alternatives without PCI certification [#alternativas]
If you do not hold PCI certification, these paths avoid that scope entirely:
- [Hosted payment page](/developers/hosted-payment-page) — Tilopay hosts the form.
- [JavaScript SDK](/developers/sdk) — the form lives on your page, but the data travels from the
browser straight to Tilopay.
- [No code](/developers/sin-codigo) — a plugin or an already-integrated platform.
---
# Environments: testing and production
> Testing and production share one host. The mode is switched from the account and verified with the test field returned by Init().
- kind: concept
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/concepts/entornos
**There is no sandbox host.** Testing and production use the same host:
`app.tilopay.com`. The URL does not tell you which mode you are in.
## How the mode is switched [#como-se-cambia]
The mode is switched **from the account in the Tilopay portal**, not from the integration.
There is no parameter, header or alternate URL that changes it from code.
## How to verify it [#como-se-verifica]
`Tilopay.Init()` returns a **`test`** field:
| Value | Meaning |
|---|---|
| `0` | Production |
| `1` | Testing |
That is the only signal available at runtime. Read it and surface it in your own checkout
while developing.
## The real risk [#riesgo]
Because the host is the same, an integrator can believe they are testing while actually
being in production, taking real money. **Verify `test` before assuming the mode.** If your
integration moves money, make an unexpected `test: 0` fail loudly in your development
environments.
---
# Safe retries and orderNumber
> The API is not idempotent. Exactly what to do when a payment call dies on a timeout.
- kind: concept
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/concepts/reintentos-seguros
**The Tilopay API is not idempotent.** There is no idempotency key and no retry that returns the
original transaction. If you come from other processors, this is the assumption to dismantle
before writing code.
## `orderNumber` is unique forever [#ordernumber]
`orderNumber` is unique per merchant **across their entire operation**, forever. It does not
reset daily, monthly or seasonally.
If it repeats, **the new transaction is rejected** with the response **"Transacción
duplicada"** (duplicate transaction). It does not return the original transaction: it returns a
rejection.
## The timeout problem [#timeout]
When a payment call dies on a network error or timeout, you do not know whether the transaction
was created. And neither intuitive way out works:
| What you would do | What happens |
|---|---|
| Retry with the same `orderNumber` | Duplicate rejection, even if the first one went through |
| Retry with a new `orderNumber` | Risk of double charge |
**On a network timeout there is no safe retry.**
## What to do instead [#que-hacer]
Query the state before deciding:
1. Call `POST /api/v1/consult` with the original `orderNumber`.
2. If the transaction exists, use its result. Do not retry.
3. If it does not exist, then you can retry — and you can reuse the same `orderNumber`, because
it was not consumed.
```text
payment → timeout
│
└─→ consult(original orderNumber)
├─ exists → use that result
└─ not found → retry
```
## Design consequences [#diseno]
- Generate the `orderNumber` in your system **before** calling the payment and persist it. If you
generate it on the fly, after a timeout you have nothing to query with.
- Never derive the `orderNumber` from something that can repeat (recycled cart number, truncated
timestamp, resettable counter).
- A "Transacción duplicada" does not mean the charge failed: it means that `orderNumber` was
already used. Query before showing the customer an error.
---
# SDK installation
> The V2 SDK script tag, which versions exist, and which versioning guarantees do not exist.
- kind: guide
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/sdk/instalacion
## The script [#script]
```html
```
Load it before your own checkout code. The SDK exposes the global `Tilopay` object.
## jQuery is not required [#jquery]
**jQuery is NOT required.** It was a leftover from SDK V1. The article published so far
said otherwise and it is wrong: you can install SDK V2 without jQuery on the page.
## Versions [#versiones]
There are only two versions:
| Version | Status |
|---|---|
| `v1` | Unsupported |
| `v2` | Current |
## What does not exist [#garantias]
**There is no immutable versioning, no SRI hash and no changelog.** The
`/sdk/v2/sdk_tpay.min.js` URL is not pinned to a specific version: its contents can change
without prior notice and without public release notes.
Practical consequences:
- You cannot set `integrity="sha384-..."` on the `script` tag, because the file changes.
- You cannot rely on a build number to reproduce a bug.
- Keep smoke tests for your checkout running periodically, not only on deploy.
## What is next [#que-sigue]
- [Form fields](/developers/sdk/campos-del-formulario) — the ids the SDK looks for.
- [`Tilopay.Init()`](/developers/sdk/reference/init) — start the purchase.
---
# Form fields
> The tlpy_* ids the V2 SDK looks for in your form, and the responseTilopay container it needs for 3DS.
- kind: concept
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/sdk/campos-del-formulario
The V2 SDK does not render the form: it takes over the inputs that already exist on your
page, finding them by `id`. Those ids are a contract — change one and the SDK stops finding
the field.
**The contract is the inputs, not the containers.** You can name the `div` elements that
wrap the fields however you want: the SDK does not look for them. The only exception is
`responseTilopay`, which is required.
## Fields [#campos]
Holds the payment method id obtained from Tilopay. It may be visible or hidden, at the
merchant's discretion.
Holds the saved card id obtained from Tilopay. If the customer has no saved cards, hide it.
Card number.
Expiration date in month/year format, for example `01/25`.
Security code. When the customer uses a saved card, this field must be enabled so they can
type the CVV.
Required container, **outside the form**. This is where the SDK mounts the 3DS flow.
## The Yappy phone does not travel through the DOM [#yappy]
The Yappy phone number is **not** read from a form field: it is sent in the `phoneYappy`
parameter of [`Init()`](/developers/sdk/reference/init) or
[`updateOptions()`](/developers/sdk/reference/update-options).
## Example structure [#estructura]
The `div` elements in this example are free-form; the input `id`s and `responseTilopay` are
not.
```html
```
---
# SDK · Tilopay.Init()
> Starts a purchase: authenticates the checkout and returns the available payment methods and the customer's saved cards.
- kind: sdk-method
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/sdk/reference/init
Starts a purchase. It authenticates the checkout with the SDK token and returns the payment
methods available to the merchant.
To save a card without charging it, the SDK has a second start flow:
**`Tilopay.InitTokenize()`**, with the same parameters as `Init()` except `amount`,
`orderNumber`, `capture` and `subscription`, which do not apply because nothing is charged.
## Signature [#firma]
```js
await Tilopay.Init({ /* parameters */ })
```
## Parameters [#parametros]
SDK token, obtained with `POST /api/v1/loginSdk`. See
[authentication](/developers/api/autenticacion).
Purchase currency, ISO 4217.
Checkout **language**, ISO 639-1. Only `es` and `en` are supported; defaults to `es`.
Purchase amount.
Customer email. Required for the response to include saved cards.
Order number, unique per merchant. See
[safe retries](/developers/concepts/reintentos-seguros).
Customer identification type. Conditional. See the
[type table](/developers/sdk/reference/update-options#tipos-de-identificacion).
Customer identification number. Conditional.
Customer first name.
Customer last name.
Customer address line 1.
Customer address line 2. Optional.
City. Recommended.
State or province. Recommended.
Postal code. Recommended.
Country, ISO 3166-1 alpha-2. Recommended.
Customer phone. Recommended.
`0` authorizes; `1` authorizes and captures.
URL where the SDK renders the final purchase response.
`1` saves the customer card in Tilopay; `0` does not save it.
Yappy phone. Required when paying with Yappy. It is not read from the DOM.
Optional. Values `"V1"` or `"V2"`. If omitted, the final response hash is built with V1.
Optional. Returned as-is in the final payment response and recovered on the transaction
response URL. Supports up to **65,535 characters**, although a very long value can affect
the response URL. You can send a base64-serialized array so it satisfies the string format.
## Call [#llamada]
```js
const init = await Tilopay.Init({
token: sdkToken,
currency: "CRC",
language: "es",
amount: 100.0,
billToEmail: "cliente@ejemplo.com",
orderNumber: "ORD-2026-000123",
billToFirstName: "Ana",
billToLastName: "Rojas",
billToAddress: "Avenida 1, Local 2",
billToCountry: "CR",
capture: 1,
redirect: "https://ejemplo.com/checkout/respuesta",
subscription: 0,
});
```
## Response [#respuesta]
`Success`, or the error description.
`0` production, `1` testing. See [environments](/developers/concepts/entornos).
Object with `code` and `amount`, present when the merchant has SINPE Móvil. The full data,
including the destination phone, is obtained with
[`getSinpeMovil()`](/developers/sdk/reference/get-sinpe-movil).
Array of `{id, name, type}` with the available payment methods.
Array of `{id, name, brand}` with the customer's saved cards.
## Payment method id format [#formato-id-metodo]
Each method `id` has the shape `A:B:C`. **The second segment defines the payment method, and
`18` corresponds to Yappy.**
## Saved cards [#tarjetas-guardadas]
- For the response to include `cards`, **`billToEmail` is required**.
- Once the cards are obtained, **the email can no longer be changed** with
[`updateOptions()`](/developers/sdk/reference/update-options).
---
# SDK · Tilopay.startPayment()
> Closes the purchase. The SDK handles the whole 3DS flow and renders the response on the redirect URL.
- kind: sdk-method
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/sdk/reference/startpayment
Closes the purchase started with [`Tilopay.Init()`](/developers/sdk/reference/init).
## Signature [#firma]
```js
await Tilopay.startPayment()
```
It takes no parameters.
## 3DS: the SDK handles it [#tres-ds]
**The SDK handles the whole 3D Secure flow.** All you have to do is make sure the
`responseTilopay` container is on the page: that is where the SDK inserts what 3DS needs and
drives the process.
```html
```
See [form fields](/developers/sdk/campos-del-formulario#campos).
## Where the result arrives [#resultado]
When it finishes, the SDK renders the response on the URL given in the `redirect` parameter of
`Init()`. **That is the final purchase response**: treat the `redirect` URL as the point where
your application decides the outcome.
On error, the method returns the description:
```json
{
"message": "error description"
}
```
---
# Tilopay.getCardType()
> Returns the brand of the card the customer is typing, so you can show an icon while they type.
- kind: sdk-method
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/sdk/reference/get-card-type
Returns the card brand from the number the customer already typed into `tlpy_cc_number`. The
typical use is showing the brand icon while the customer types.
## Signature [#firma]
```js
await Tilopay.getCardType()
```
It takes no parameters.
**Precondition:** the customer must have already typed the card number.
## Call [#llamada]
```js
const type = await Tilopay.getCardType();
```
## Response [#respuesta]
```json
{
"message": "visa"
}
```
The card brand.
## Supported brands [#marcas-soportadas]
VISA · MASTERCARD · AMEX
Use the result for presentation only: brand validation happens when Tilopay processes the
charge, not in this method.
---
# Tilopay.getSinpeMovil()
> Returns the data to show the customer to pay via SINPE Móvil and activates the collection listener.
- kind: sdk-method
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/sdk/reference/get-sinpe-movil
SINPE Móvil is not charged from the form: the customer makes the transfer from their own bank.
This method returns the data you must show them — destination phone, exact amount and
description code.
## When to use it [#cuando]
When the merchant has a SINPE Móvil method available and the customer selects it from the list
returned by [`Init()`](/developers/sdk/reference/init).
**It is not just a getter.** Besides returning the data, this method **triggers the SINPE
listener with the Tilopay backend**. Calling it is part of the collection flow, not a
presentation detail.
## Signature [#firma]
```js
await Tilopay.getSinpeMovil()
```
It takes no parameters.
**Preconditions:**
- The customer must have selected SINPE Móvil as the payment method.
- `typeDni` and `dni` must have been sent earlier, via `Init()` or
[`updateOptions()`](/developers/sdk/reference/update-options).
## Call [#llamada]
```js
const params = await Tilopay.getSinpeMovil();
```
## Response [#respuesta]
```json
{
"message": "Success",
"code": "863",
"amount": 10,
"number": "70599200"
}
```
`Success` when the operation succeeded.
The code the customer must write in the transfer description. It is what identifies the payment.
The exact amount they must transfer.
The destination phone number for the transfer.
### On error [#respuesta-de-error]
**On error it returns nothing.** Do not expect an object with empty fields: treat the absence of
a response as the error case.
## What to do with this data [#que-hacer]
When SINPE Móvil is selected, hide the card fields and show the customer this data: destination
phone, exact amount and the code for the description.
**No pay button is needed:** the collection is processed when the transfer arrives.
---
# Tilopay.updateOptions()
> Partially updates the parameters sent to Init() when they change before closing the payment.
- kind: sdk-method
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/sdk/reference/update-options
Updates values already sent in [`Tilopay.Init()`](/developers/sdk/reference/init) that changed
during checkout — typically when the customer edits their data, or when they select SINPE Móvil
or Yappy and information that did not apply before must be added.
**It is a patch.** Send only the fields you want to update; there is no need to resend everything.
## What "required" means here [#obligatorio]
In the list below, "required" means the field **must have been sent either in `Init()` or in
`updateOptions()`**. If it was never sent in either, the payment cannot proceed. It does not mean
you must resend it on every call.
## Signature [#firma]
```js
await Tilopay.updateOptions({ /* only the fields that change */ })
```
## Call [#llamada]
```js
const update = await Tilopay.updateOptions({
typeDni: 1,
dni: "0707770777",
billToFirstName: "Ana",
billToLastName: "Rojas",
});
```
## Parameters [#parametros]
Customer identification type. Required for SINPE Móvil. See
[identification types](#tipos-de-identificacion).
Customer identification number. Required for SINPE Móvil. **Accepted with and without hyphens.**
Customer first name.
Customer last name.
Customer address line 1.
Customer address line 2. Optional.
Customer city. Recommended.
State or province. Recommended.
Postal code. Recommended.
Country, ISO 3166-1 alpha-2. Recommended.
Customer phone. Recommended.
`0` authorizes; `1` authorizes and captures.
URL where the final purchase response is expected.
`1` if the customer wants to save their card in Tilopay; `0` if not.
Yappy phone. Required when the customer pays with Yappy.
**`billToEmail` cannot be updated after saved cards are obtained.** Once `Init()` returned the
customer's cards, the email cannot be changed through this method.
## Identification types [#tipos-de-identificacion]
Applies to the `typeDni` parameter, both here and in `Tilopay.Init()`. In the masks, `#` is a
**numeric** character and `&` is **alphanumeric**. Lengths do not count hyphens.
| Code | Type | Format | Length |
|---|---|---|---|
| 1 | Cédula de identidad | `0#-####-####` | 10 |
| 2 | Cédula jurídica | `3-###-######` | 10 |
| 3 | Gobierno central | `2-###-######` | 10 |
| 4 | Institución autónoma | `4-###-######` | 10 |
| 5 | Extranjero no residente | `9&&&&&&&&&&&&&&&&&&&` | 20 |
| 6 | DIMEX | `1###########` | 12 |
| 7 | DIDI | `5###########` | 12 |
## Response [#respuesta]
```json
{
"message": "Success"
}
```
`Success` when the update succeeded; the error description otherwise.
---
# API · Authentication
> How to get the API token and the SDK token, how long each lasts, and how to send them on every call.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/api/autenticacion
The whole API and the SDK live on a single host: `https://app.tilopay.com`. There is no
separate host for testing — see [environments](/developers/concepts/entornos).
## The two operations [#operaciones]
| Operation | Path | What for |
|---|---|---|
| API token | `POST /api/v1/login` | Server-to-server API calls |
| SDK token | `POST /api/v1/loginSdk` | The token passed to `Tilopay.Init()` |
`loginSdk` is the method the previous article called "GetTokenSdk". It is the same one.
## Get the API token [#token-api]
```bash
curl -X POST https://app.tilopay.com/api/v1/login \
-H "Content-Type: application/json" \
-d '{ "apiuser": "YOUR_APIUSER", "password": "YOUR_PASSWORD" }'
```
### Body [#cuerpo]
The merchant API user.
The merchant API password.
### Response [#respuesta]
The token to send on subsequent calls.
Always `bearer`.
Token lifetime. The exact value comes in this response: do not assume it on the client.
## Get the SDK token [#token-sdk]
```bash
curl -X POST https://app.tilopay.com/api/v1/loginSdk \
-H "Content-Type: application/json" \
-d '{ "apiuser": "YOUR_APIUSER", "password": "YOUR_PASSWORD" }'
```
The resulting token is the one passed to the `token` parameter of
[`Tilopay.Init()`](/developers/sdk/reference/init).
## Lifetime [#vigencia]
- **API token: 24 hours.**
- **SDK token: 1 hour.**
The exact value always arrives in `expires_in`. Cache it server-side and renew on expiry.
## How it is sent [#envio]
```http
Authorization: bearer
```
## Revocation and limits [#revocacion]
- **Tokens cannot be revoked.** If a token leaks there is no operation to invalidate it:
treat the leak as an incident and rotate credentials with Tilopay.
- **There is no limit** on concurrent tokens per merchant. You can request one per process
without invalidating the previous ones.
## Where credentials come from [#credenciales]
`apiuser`, `password` and `key` are obtained in the merchant panel at
`admin.tilopay.com/admin/checkout`. If you do not have access yet, start with
[developer registration](/developers/registro).
Never put `apiuser` or `password` in the browser. The login runs on your server; only the
SDK token reaches the browser.
---
# API · Get API token
> API login operation: returns the bearer token that signs every other call.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/autenticacion/token-api
```http
POST /api/v1/login
```
## What it does [#que-hace]
Returns the security token needed to consume the API services. The API user and password come from [Admin · Tilopay Checkout](https://admin.tilopay.com/admin/checkout).
## Authentication [#autenticacion]
It does not require a token: this is the operation that issues it. See [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Merchant API user, obtained in Admin · Tilopay Checkout.
Merchant API password, obtained in Admin · Tilopay Checkout.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"apiuser": "",
"password": ""
}
```
## Response [#respuesta]
```json
{
"access_token": "",
"token_type": "bearer",
"expires_in": 86400
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Get SDK token
> SDK login: returns the token that Tilopay.Init() uses in the browser.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/autenticacion/token-sdk
```http
POST /api/v1/loginSdk
```
## What it does [#que-hace]
Returns the security token needed to consume the SDK. All three credentials come from [Admin · Tilopay Checkout](https://admin.tilopay.com/admin/checkout).
## Authentication [#autenticacion]
It does not require a token: this is the operation that issues it. See [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Merchant API user.
Merchant API password.
Merchant api key.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"apiuser": "",
"password": "",
"key": ""
}
```
## Response [#respuesta]
```json
{
"access_token": "351d477adaaa51cdbb33ae4b4b8c843aa759f131c1c38415180b5035543d59d2f23f4e049706f5fa71c5f0d9ff763960a3cd035b4c1cefa428c90bedb672f780",
"token_type": "bearer",
"expires_in": "2023-06-05 13:32:06"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Hosted payment page
> Hosted payment page operations of the Tilopay API, with parameters and examples.
- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/hosted-payment-page
## Operations [#operaciones]
- [processPayment](/developers/api/hosted-payment-page/process-payment)
The conceptual side of this path —requirements, callback and status confirmation— lives in [hosted payment page](/developers/hosted-payment-page).
Every operation lives on `https://app.tilopay.com` and, except for the login operations, requires the API token — see [authentication](/developers/api/autenticacion).
---
# API · processPayment
> Parameters, request example and response of processPayment, the operation that opens the payment form.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/hosted-payment-page/process-payment
```http
POST /api/v1/processPayment
```
## What it does [#que-hace]
Returns the URL of the payment form for a purchase.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Site where you wait for the transaction response, for example `mywebsite.com`. It must support the **GET** method. Example response to the redirect: `mywebsite.com?code=1&description=Transaction%20is%20approved.&auth=123456&order=TPYS-881WROIBQA1405468&tpt=4300&crd=&tilopay-transaction=4300&OrderHash=b02927cb...&returnData=Tilopay-dataReturn123456789&form_update=ok`. When `code = 1` the transaction is approved; anything else is declined. `OrderHash` is a unique string per transaction: to use it on the merchant side, write to `sac@tilopay.com` for instructions.
Key associated with the customer. It is obtained in Admin · Tilopay Checkout.
Purchase amount.
Purchase currency in ISO format, for example USD, CRC, GTQ.
Order number, it can be alphanumeric.
Capture and authorize: 1 yes, 0 no.
First name.
Last names.
Address.
Address 2.
City.
State in ISO format, for example CR-SJ (San José, Costa Rica) or US-CA (California, USA).
Post code.
Country in ISO Alpha-2 code, for example CR (Costa Rica), US (USA) or GT (Guatemala).
Telephone.
Buyer email.
First name.
Last names.
Address.
Address 2.
City.
State in ISO format, for example CR-SJ (San José, Costa Rica) or US-CA (California, USA).
Post code.
Country in ISO Alpha-2 code, for example CR (Costa Rica), US (USA) or GT (Guatemala).
Telephone.
1 to force the customer to save the card in Tilopay, 0 not to.
Name of the platform where the transaction is generated.
Value that Tilopay returns in the final response. Sending a base 64 string is recommended.
Only used when implementing hash verification. Possible values [V1, V2]; V1 by default.
Send as value "v2".
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"redirect": "https://www.urlToRedirect.com",
"key": "",
"amount": "1.00",
"currency": "USD",
"orderNumber": "1212122",
"capture": "1",
"billToFirstName": "DEMO",
"billToLastName": "DEMO",
"billToAddress": "San Jose",
"billToAddress2": "Catedral",
"billToCity": "JS",
"billToState": "SJ",
"billToZipPostCode": "10061",
"billToCountry": "CR",
"billToTelephone": "88888888",
"billToEmail": "cliente@ejemplo.com",
"shipToFirstName": "DEMO",
"shipToLastName": "DEMO",
"shipToAddress": "San Jose",
"shipToAddress2": "Catedral",
"shipToCity": "JS",
"shipToState": "SJ",
"shipToZipPostCode": "10061",
"shipToCountry": "CR",
"shipToTelephone": "88888888",
"subscription": "0",
"platform": "api",
"returnData": "dXNlcl9pZD0xMg==",
"hashVersion": "V2",
"token_version": "v2"
}
```
## Response [#respuesta]
```json
{
"type": "100",
"html": "Use url redirect",
"url": "https://secure.tilopay.com/htmls/1212122_574572148file.html"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Operational processes
> Operational processes operations of the Tilopay API, with parameters and examples.
- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/procesos-operativos
## Operations [#operaciones]
- [processModification](/developers/api/procesos-operativos/process-modification)
- [consult](/developers/api/procesos-operativos/consult)
- [consultTransactions](/developers/api/procesos-operativos/consult-transactions)
- [Split settlement](/developers/api/procesos-operativos/split)
These operations are cross-cutting: they work for any of the four [integration paths](/developers), no matter how the charge was originated.
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
Every operation lives on `https://app.tilopay.com` and, except for the login operations, requires the API token — see [authentication](/developers/api/autenticacion).
---
# API · processModification
> Capture, refund and reversal of a transaction with processModification.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/procesos-operativos/process-modification
```http
POST /api/v1/processModification
```
## What it does [#que-hace]
Modifies an already processed transaction: capture, refund or reversal.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Example: `1214352`
Example: `2`
Example: `1.00`
Key associated with the customer. It is obtained in Admin · Tilopay Checkout.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"orderNumber": "1214352",
"type": "2",
"amount": "1.00",
"key": ""
}
```
## Response [#respuesta-modificacion]
Type of modification applied.
Transaction identifier.
Result code of the modification.
Result text.
Order hash. See the note about `orderHash` in [webhooks](/developers/api/webhooks#verificacion).
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · consult
> Query the status and processed amount of a single transaction.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/procesos-operativos/consult
```http
POST /api/v1/consult
```
## What it does [#que-hace]
Queries a specific transaction: returns the processed amount and the status of the transaction.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Order number being queried.
Merchant id.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"orderNumber": "1212122",
"merchantId": ""
}
```
## Response [#respuesta]
```json
{
"type": "200",
"message": "",
"response": [
{
"id_tilopay": 734312,
"orderNumber": "1212122",
"amount": "5.00",
"currency": "USD",
"merchantId": "88803956",
"code": "1",
"response": "Transacción aprobada",
"auth": "123456",
"commission": 0.18,
"iva_commission": 0.02,
"retention_iva": 0.27,
"retention_rent": 0.09,
"cost": 0.35,
"cost_iva": 0.05,
"net_to_liquidate": "4.04",
"capture": "Capture",
"card": "4021",
"last": "5221",
"environment": "Test",
"type": "Payment",
"date": "2024-07-31 16:59:20"
}
]
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · consultTransactions
> Bulk transaction query by date range, currency, order or email.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/procesos-operativos/consult-transactions
```http
POST /api/v1/consultTransactions
```
## What it does [#que-hace]
Queries transactions by date range, with optional filters.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Start date, `Y-m-d H:i:s` format — for example "2022-01-15 00:00:00".
End date, `Y-m-d H:i:s` format — for example "2022-08-01 23:59:59".
Whether to return only approved transactions.
| Code | Value |
| --- | --- |
| 0 | Any |
| 1 | Approved only |
Environment of the transactions to return.
| Code | Value |
| --- | --- |
| 0 | Production |
| 1 | Test |
Array of currencies to return, for example ["USD", "CRC"].
Merchant id.
Order number.
Customer email.
Authorization number.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"startDate": "2023-06-01 00:00:00",
"endDate": "2023-06-30 23:59:59",
"onlyAproved": 1,
"environment": 1,
"currency": [
"USD",
"CRC"
],
"merchantId": "",
"orderNumber": "12135",
"email": "customer@example.com",
"auth": "123456"
}
```
## Response [#respuesta]
```json
{
"type": "200",
"message": "",
"response": [
{
"id": 734329,
"orderNumber": "12135",
"amount": "5.00",
"taxes": "0.00",
"discount": "0.00",
"discount_name": "",
"currency": "USD",
"merchantId": "",
"code": "1",
"response": "Transacción aprobada",
"auth": "123456",
"card": "4021",
"last": "5221",
"email": "customer@example.com",
"commission": 0.18,
"iva_commission": 0.02,
"retention_iva": 0.27,
"retention_rent": 0.09,
"cost": 0.35,
"cost_iva": 0.05,
"net_to_liquidate": 4.04,
"capture": "Capture",
"type": "Payment",
"environment": "Production",
"date": "2024-07-31 16:59:20"
},
{
"id": 734330,
"orderNumber": "12136",
"amount": "5.00",
"taxes": "0.00",
"discount": "0.00",
"discount_name": "",
"currency": "USD",
"merchantId": "",
"code": "1",
"response": "Transacción aprobada",
"auth": "123456",
"card": "4021",
"last": "5221",
"email": "customer@example.com",
"commission": 0.18,
"iva_commission": 0.02,
"retention_iva": 0.27,
"retention_rent": 0.09,
"cost": 0.35,
"cost_iva": 0.05,
"net_to_liquidate": 4.04,
"capture": "Capture",
"type": "Payment",
"environment": "Production",
"date": "2024-07-31 17:25:35"
}
]
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Split settlement
> Splitting the settlement of an order among several facilitated merchants.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/procesos-operativos/split
```http
POST /api/v1/orders/liquidation/split
```
## What it does [#que-hace]
Splits the settlement of an order among several merchants. It only applies to merchants that use Tilopay as a payment facilitator, and the resulting orders are identified by the `SL|` prefix.
Rules:
- The merchants must be approved and be from the same country.
- If the split is lower than the total amount of the order, the remainder is assigned to the merchant that made the original transaction.
- It only applies to fully approved orders.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Id of the order approved in Tilopay.
Associative array with the `email` and `amount` keys of every merchant the settlement is divided with. Including the owner merchant is optional: when its amount is not specified the remainder of the split is assigned to it, and when it is included and there is a remainder, the remainder is added to it.
Request language.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"order_id": "1",
"commerces": [
{
"email": "commerce-1@example.com",
"amount": "7.5"
},
{
"email": "commerce-2@example.com",
"amount": "5.5"
}
],
"lang": "en"
}
```
## Response [#respuesta]
```json
{
"type": "200",
"message": "Great",
"description": "Order splitted successfully",
"response": {
"total_order_splitted": 3,
"order_id": 1,
"order_number": "PFC000069-TYP785237_313",
"order_key": "",
"order_currency": "USD",
"order_amount": "33.00",
"splitted_orders": [
{
"id": 1,
"amount": 20,
"commerce_name": "Commerce owner name",
"commerce_email": "owner@example.com"
},
{
"id": 2,
"amount": 7.5,
"commerce_name": "Commerce name",
"commerce_email": "commerce-1@example.com"
},
{
"id": 3,
"amount": 5.5,
"commerce_name": "Commerce name",
"commerce_email": "commerce-2@example.com"
}
]
}
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · How to read an error response
> An HTTP 200 does not mean success. Where the issuer decline arrives and how to write error handling.
- kind: concept
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/api/procesos-operativos/errors
## The issuer decline [#rechazo]
When the issuer declines a transaction, the response carries two fields:
The issuer decline code.
The decline text.
## An HTTP 200 does not mean success [#estado-http]
**There is no defined standard for when the API responds HTTP 4xx and when it responds HTTP 200
with the error in the body.** Both forms coexist, and there are **four different error envelopes
depending on the endpoint**.
Practical consequence: your error handling must always look at the body, not only the status
code, and tolerate more than one body shape.
## How to write error handling [#como-manejar]
- Treat `code` and `description` as data to log and display, not as an enumeration to branch on.
- Do not write `if (status === 200) success`. Check the body.
- Store the raw response of every decline: it is what lets you reconstruct your merchant's
decline pattern.
- To determine the real state of a transaction after a failure, use
[safe retries](/developers/concepts/reintentos-seguros).
---
# API · Recurring
> Recurring operations of the Tilopay API, with parameters and examples.
- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes
## Operations [#operaciones]
17 operations in four subgroups:
- [Charge a payment](/developers/api/recurrentes/realizar-pago) — 1
- [Plans](/developers/api/recurrentes/planes) — 5
- [Subscribers](/developers/api/recurrentes/suscriptores) — 7
- [Coupons](/developers/api/recurrentes/cupones) — 4
Every operation lives on `https://app.tilopay.com` and, except for the login operations, requires the API token — see [authentication](/developers/api/autenticacion).
---
# API · Recurring · Charge a payment
> Recurring · Charge a payment operations of the Tilopay API, with parameters and examples.
- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/realizar-pago
## Operations [#operaciones]
- [processRecurrentPayment](/developers/api/recurrentes/realizar-pago/process-recurrent-payment)
Every operation lives on `https://app.tilopay.com` and, except for the login operations, requires the API token — see [authentication](/developers/api/autenticacion).
---
# API · processRecurrentPayment
> Server-to-server charge with a v2 card token through processRecurrentPayment.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/realizar-pago/process-recurrent-payment
```http
POST /api/v1/processRecurrentPayment
```
## What it does [#que-hace]
Processes a charge with an already tokenized card, without a form.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Key associated with the customer. It is obtained in Admin · Tilopay Checkout.
Purchase amount.
Purchase currency in ISO format, for example USD, CRC, GTQ.
Order number, it can be alphanumeric.
Capture and authorize: 1 yes, 0 no.
Cardholder email.
Card token. It must be the v2 token.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"amount": "10.00",
"currency": "USD",
"orderNumber": "1213",
"capture": "1",
"email": "myemail@exapmle.com",
"card": "511111_00GOB1111"
}
```
## Response [#respuesta]
```json
{
"type": "200",
"response": "1",
"description": "Transacción aprobada",
"auth": "123456",
"tpt": 734329,
"order_id": "12135",
"tilopayTransaction": 734329,
"orderHash": "f3ad85046d249bc7a781eed5285a5ded92045a2e11108063504deec72ec9b338"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Recurring · Plans
> Recurring · Plans operations of the Tilopay API, with parameters and examples.
- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/planes
## Operations [#operaciones]
- [Create recurring plan](/developers/api/recurrentes/planes/create-plan)
- [Edit recurring plan](/developers/api/recurrentes/planes/edit-plan)
- [Get a recurring plan](/developers/api/recurrentes/planes/get-plan)
- [List recurring plans](/developers/api/recurrentes/planes/get-plans)
- [Delete recurring plan](/developers/api/recurrentes/planes/delete-plan)
Every operation lives on `https://app.tilopay.com` and, except for the login operations, requires the API token — see [authentication](/developers/api/autenticacion).
---
# API · Create recurring plan
> Recurring plan creation: frequencies, free trial, modalities and webhooks.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/planes/create-plan
```http
POST /api/v1/createPlanRepeat
```
## What it does [#que-hace]
Creates a subscription plan: charge frequency, currency, trial period, modalities and webhooks.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Recurring plan title.
Plan description.
Charge frequency.
| Code | Value |
| --- | --- |
| 1 | Daily |
| 2 | Weekly |
| 3 | Monthly |
| 4 | Yearly |
| 5 | Fortnightly |
| 6 | Every two months |
| 7 | Quarterly |
| 8 | Every four months |
| 9 | Every six months |
Currency code in ISO 4217 format.
Initial payment amount.
Enables the free trial period: 0 no, 1 yes.
Days of the free trial period.
Number of retries for failed charges.
Array of plan modalities.
Optional field. The merchant's own thank-you URL; it must support the **GET** method.
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when a customer successfully takes out a subscription. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'modality' : 'ModalityName', 'amount' : 25, 'frequency' : '', 'coupon' : '5HT5W8YT', 'free_trial' : 1, 'next_payment_date' : '2023-02-25'}`
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when the customer is charged successfully. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'amount' : 25, 'auth' : '123456', 'orderNumber' : 'PRE123456'}`
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when a payment fails. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'amount' : 25}`
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when a customer cancels the subscription to one of their plans. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'expire' : '2023-02-25'}`
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when a customer reactivates the subscription to one of their plans. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'next_payment_date' : '2023-02-25'}`
End date of the recurring plan, `d-m-Y` format (for example 25-09-2022). When the plan has no end date, send it empty.
Set to 1 it adds the `notify_detail` and `notify_note` text to the notification email. Set to 0 it adds neither.
Detail text in Spanish. Optional when `notify` is 0.
Detail text in English. Optional when `notify` is 0.
Notes text in Spanish. Optional when `notify` is 0.
Notes text in English. Optional when `notify` is 0.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"title": "Plan title",
"description": "Plan description",
"frecuency": 1,
"currency": "USD",
"first_amount": 0,
"trial": 0,
"trial_days": 0,
"attempts": 1,
"modality": [
{
"title": "Basic",
"amount": 10
},
{
"title": "Premium",
"amount": 30
}
],
"thanks_url": "",
"webhook_subscribe": "",
"webhook_payment": "",
"webhook_rejected": "",
"webhook_unsubscribe": "",
"webhook_reactive": "",
"end_at": "25-10-2023",
"notify": 0,
"notify_detail_es": "",
"notify_detail_en": "",
"notify_note_es": "",
"notify_note_en": ""
}
```
## Response [#respuesta]
```json
{
"type": "200",
"status": 1,
"message": "Success",
"id": 624,
"url": "https://app.tilopay.com/link/TmpJMHwx"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Edit recurring plan
> Editing a recurring plan and its status.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/planes/edit-plan
```http
POST /api/v1/editPlanRepeat
```
## What it does [#que-hace]
Edits an existing plan, including its status.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Recurring plan id.
Recurring plan title.
Plan description.
Charge frequency.
| Code | Value |
| --- | --- |
| 1 | Daily |
| 2 | Weekly |
| 3 | Monthly |
| 4 | Yearly |
| 5 | Fortnightly |
| 6 | Every two months |
| 7 | Quarterly |
| 8 | Every four months |
| 9 | Every six months |
Currency code in ISO 4217 format.
Initial payment amount.
Enables the free trial period: 0 no, 1 yes.
Days of the free trial period.
Number of retries for failed charges.
Status of the recurring plan.
| Code | Value |
| --- | --- |
| 0 | Inactive |
| 1 | Active |
| 2 | Active but with no new sign-ups |
Optional field. The merchant's own thank-you URL; it must support the **GET** method.
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when a customer successfully takes out a subscription. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'modality' : 'ModalityName', 'amount' : 25, 'frequency' : '', 'coupon' : '5HT5W8YT', 'free_trial' : 1, 'next_payment_date' : '2023-02-25'}`
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when the customer is charged successfully. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'amount' : 25, 'auth' : '123456', 'orderNumber' : 'PRE123456'}`
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when a payment fails. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'amount' : 25}`
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when a customer cancels the subscription to one of their plans. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'expire' : '2023-02-25'}`
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when a customer reactivates the subscription to one of their plans. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'next_payment_date' : '2023-02-25'}`
End date of the recurring plan, `d-m-Y` format (for example 25-09-2022). When the plan has no end date, send it empty.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id": 3,
"title": "Plan title",
"description": "Plan description",
"frecuency": 2,
"currency": "USD",
"first_amount": 0,
"trial": 0,
"trial_days": 0,
"attempts": 5,
"status": 1,
"thanks_url": "",
"webhook_subscribe": "",
"webhook_payment": "",
"webhook_rejected": "",
"webhook_unsubscribe": "",
"webhook_reactive": "",
"end_at": "25-10-2023"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Get a recurring plan
> Query of a recurring plan by id.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/planes/get-plan
```http
POST /api/v1/getPlanRepeat
```
## What it does [#que-hace]
Returns a single recurring plan.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Recurring plan id.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id": "3"
}
```
## Response [#respuesta]
```json
{
"type": "200",
"message": "Success",
"plan": {
"id": 232,
"title": "Prueba repeat",
"description": "Plan repeat de prueba mensual",
"frequency": 3,
"currency": "USD",
"first_amount": "5.00",
"trial": 0,
"trial_days": 0,
"attempts": 5,
"thanks_url": null,
"webhook_subscribe": null,
"webhook_payment": null,
"webhook_rejected": null,
"webhook_unsubscribe": null,
"webhook_reactive": null,
"modality": [
{
"id": 292,
"title": "Pago mensual prueba repeat modalidad",
"amount": "10.00"
}
],
"end_at": null
}
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · List recurring plans
> Listing of the integration's recurring plans.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/planes/get-plans
```http
POST /api/v1/getPlansRepeat
```
## What it does [#que-hace]
Returns the merchant's recurring plans.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": ""
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Delete recurring plan
> Deletion of a recurring plan by id.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/planes/delete-plan
```http
POST /api/v1/deletePlanRepeat
```
## What it does [#que-hace]
Deletes a recurring plan.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Recurring plan id.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id": "625"
}
```
## Response [#respuesta]
```json
{
"type": "200",
"status": 1,
"message": "Success"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Recurring · Subscribers
> Recurring · Subscribers operations of the Tilopay API, with parameters and examples.
- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/suscriptores
## Operations [#operaciones]
- [Subscribers of a plan](/developers/api/recurrentes/suscriptores/get-suscriptor-plan)
- [Edit subscriber](/developers/api/recurrentes/suscriptores/edit-suscriptor-plan)
- [Pause subscriber](/developers/api/recurrentes/suscriptores/pause-suscriptor-plan)
- [Reactivate subscriber](/developers/api/recurrentes/suscriptores/reactive-suscriptor-plan)
- [Delete subscriber](/developers/api/recurrentes/suscriptores/delete-suscriptor-plan)
- [Registration and renewal URL](/developers/api/recurrentes/suscriptores/consult-url)
- [Subscriber payments](/developers/api/recurrentes/suscriptores/suscriptor-payments)
Every operation lives on `https://app.tilopay.com` and, except for the login operations, requires the API token — see [authentication](/developers/api/autenticacion).
---
# API · Subscribers of a plan
> Query of the subscribers of a recurring plan.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/suscriptores/get-suscriptor-plan
```http
POST /api/v1/getSuscriptorRepeat
```
## What it does [#que-hace]
Returns the subscribers associated with a recurring plan.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Recurring plan id.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id": "2"
}
```
## Response [#respuesta]
```json
{
"type": "200",
"message": "Success",
"suscriptor": [
{
"id": 360,
"name": "Jhon 1",
"lastname": "D",
"email": "customer1@example.com",
"modality": "Pago mensual prueba repeat modalidad",
"amount": "10.00",
"expire": "2023-03-26",
"coupon": "",
"status": "Delete",
"create": "2022-10-19 12:48:59"
},
{
"id": 33364,
"name": "Jhon 2",
"lastname": "D",
"email": "customer2@example.com",
"modality": "Pago mensual prueba repeat modalidad",
"amount": "10.00",
"expire": "2023-08-05",
"coupon": "",
"status": "Active",
"create": "2023-06-05 14:24:18"
}
]
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Edit subscriber
> Editing the status and expiration of a subscriber.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/suscriptores/edit-suscriptor-plan
```http
POST /api/v1/editSuscriptorRepeat
```
## What it does [#que-hace]
Changes the status or the expiration date of a subscriber.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Subscriber id.
Status of the subscriber.
| Code | Value |
| --- | --- |
| 1 | Active |
| 3 | Paused |
| 4 | Deleted |
Plan expiration date, `yy-m-d` format.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id": "2",
"status": "2",
"expire": "2023-10-25"
}
```
## Response [#respuesta]
```json
{
"type": "200",
"status": 1,
"message": "Success"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Pause subscriber
> Pausing a subscriber's subscription.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/suscriptores/pause-suscriptor-plan
```http
POST /api/v1/pauseSuscriptorRepeat
```
## What it does [#que-hace]
Pauses a subscriber's subscription.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Subscriber id.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id_suscriptor": "1"
}
```
## Response [#respuesta]
```json
{
"type": "200",
"status": 1,
"message": "Success"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Reactivate subscriber
> Reactivation of a subscriber's subscription.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/suscriptores/reactive-suscriptor-plan
```http
POST /api/v1/reactiveSuscriptorRepeat
```
## What it does [#que-hace]
Reactivates a paused subscriber's subscription.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Subscriber id.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id_suscriptor": "1"
}
```
## Response [#respuesta]
```json
{
"type": "200",
"status": 1,
"message": "Success"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Delete subscriber
> Deletion of a subscriber from a recurring plan.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/suscriptores/delete-suscriptor-plan
```http
POST /api/v1/deleteSuscriptorRepeat
```
## What it does [#que-hace]
Deletes a subscriber from a recurring plan.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Subscriber id.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id_suscriptor": "1"
}
```
## Response [#respuesta]
```json
{
"type": "200",
"status": 1,
"message": "Success"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Registration and renewal URL
> Registration or renewal URL of a recurring plan for a given email.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/suscriptores/consult-url
```http
POST /api/v1/recurrentUrl
```
## What it does [#que-hace]
Returns the registration URL of a recurring plan for a new user, or the renewal URL when the email is already registered.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Recurring plan id.
Email of the user the registration link is created for.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id": "1",
"email": "email@user.com"
}
```
## Response [#respuesta]
```json
{
"type": "200",
"message": "",
"url_register": "https://app.tilopay.com/admin/recurrent/register/MjMy?email=email@user.com",
"url_renew": ""
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Subscriber payments
> Payment history of the subscribers of a recurring plan.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/suscriptores/suscriptor-payments
```http
POST /api/v1/getSuscriptorPayments
```
## What it does [#que-hace]
Returns the payments of the subscribers of a recurring plan.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Recurring plan id.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id": "1"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Recurring · Coupons
> Recurring · Coupons operations of the Tilopay API, with parameters and examples.
- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/cupones
## Operations [#operaciones]
- [Create coupon](/developers/api/recurrentes/cupones/create-coupon)
- [List coupons of a plan](/developers/api/recurrentes/cupones/get-coupons)
- [Get a coupon](/developers/api/recurrentes/cupones/get-coupon)
- [Delete coupon](/developers/api/recurrentes/cupones/delete-coupon)
Every operation lives on `https://app.tilopay.com` and, except for the login operations, requires the API token — see [authentication](/developers/api/autenticacion).
---
# API · Create coupon
> Creation of discount coupons for recurring plans.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/cupones/create-coupon
```http
POST /api/v1/createCoupon
```
## What it does [#que-hace]
Creates a discount coupon for a recurring plan: discount type, expiration, user and email permissions, and usage limits.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Recurring plan id.
User permission.
| Code | Value |
| --- | --- |
| 0 | Allow new users only |
| 1 | Allow already registered users |
Discount type.
| Code | Value |
| --- | --- |
| 1 | Percentage |
| 2 | Fixed amount |
Numeric value of the discount.
Coupon expiration date, `Y-m-d` format (for example 2025-10-20).
Email permission.
| Code | Value |
| --- | --- |
| 1 | Specific emails |
| 2 | Any email |
Comma-separated list of emails. Required when `email_group` is sent as 1.
Total number of uses.
Total number of valid renewals.
Total uses by the same user.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"planId": 10,
"active_users": 1,
"type_discount": 1,
"discount": 40,
"expire": "2025-10-20",
"email_group": 1,
"email": "cliente@ejemplo.com, cliente@ejemplo.com",
"usage": 1,
"renews": 2,
"renews_by_user": 2
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · List coupons of a plan
> Listing of the coupons of a recurring plan.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/cupones/get-coupons
```http
POST /api/v1/getRepeatCoupons
```
## What it does [#que-hace]
Returns the coupons associated with a recurring plan.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Recurring plan id.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id": "1"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Get a coupon
> Query of a recurring coupon by id.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/cupones/get-coupon
```http
POST /api/v1/getCoupon
```
## What it does [#que-hace]
Returns a single coupon.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Coupon id.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id": "1"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Delete coupon
> Deletion of a recurring coupon by id.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/recurrentes/cupones/delete-coupon
```http
POST /api/v1/deleteCoupon
```
## What it does [#que-hace]
Deletes a coupon.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Coupon id.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id": "1"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Tokenization
> Tokenization operations of the Tilopay API, with parameters and examples.
- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/tokenizacion
## Operations [#operaciones]
- [processTokenize](/developers/api/tokenizacion/process-tokenize)
- [Remove card](/developers/api/tokenizacion/remove-card)
Every operation lives on `https://app.tilopay.com` and, except for the login operations, requires the API token — see [authentication](/developers/api/autenticacion).
---
# API · processTokenize
> Card tokenization with processTokenize: parameters, request and response.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/tokenizacion/process-tokenize
```http
POST /api/v1/processTokenize
```
## What it does [#que-hace]
Tokenizes a card: returns the URL of the tokenization form.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Site where you wait for the transaction response.
Key associated with the merchant.
Cardholder email.
Language [es, en].
Cardholder first name.
Cardholder last name.
Send as value "v2".
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"redirect": "https://urlToRedirect.com",
"key": "",
"email": "email@user.com",
"language": "es",
"firstName": "name",
"lastName": "lastname",
"token_version": "v2"
}
```
## Response [#respuesta]
```json
{
"type": "100",
"url": "https://secure.tilopay.com/htmls/TOK-5063-740506121440_1648145457file.html"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Remove card
> Removal of a saved card token from the merchant's private vault.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/tokenizacion/remove-card
```http
POST /api/v1/user/card-remove
```
## What it does [#que-hace]
Removes a saved card token. **Requirement:** the merchant must have a private token vault.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Key associated with the merchant.
Customer email associated with the token.
Token to remove.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "1234-1234-1234-1234-1234",
"email": "email@card.com",
"token": "411111.......1111"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Payment links
> Payment links operations of the Tilopay API, with parameters and examples.
- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/links-de-pago
## Operations [#operaciones]
- [Create payment link](/developers/api/links-de-pago/create-link-payment)
- [Payment link detail](/developers/api/links-de-pago/detail-link-payment)
- [Delete a payment link](/developers/api/links-de-pago/delete-link-payment)
- [List payment links](/developers/api/links-de-pago/payment-item-list)
- [Get a payment link by id](/developers/api/links-de-pago/payment-by-id)
Every operation lives on `https://app.tilopay.com` and, except for the login operations, requires the API token — see [authentication](/developers/api/autenticacion).
---
# API · Create payment link
> Payment link creation through the API, with response callback and webhook.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/links-de-pago/create-link-payment
```http
POST /api/v1/createLinkPayment
```
## What it does [#que-hace]
Creates a payment link with amount, currency and usage behaviour.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Amount of the payment link.
Currency code in ISO 4217 format.
Reference of the payment link.
Link type: 0 unlimited, 1 single use.
Payment description.
Customer name. It only applies when `type` is 1.
Optional field. URL, over **GET**, the customer is redirected to with the response once the payment is completed. Example of the data sent: `code=Val&description=Val&auth=Val&tilopayLinkId=Val&orderNumber=Val&tilopayOrderId=Val&creditCardToken=Val&creditCardBrand=Val&last4CreditCardNumber=Val&orderHash=Val`
Optional field. URL to send the response webhook to once the payment is completed.
It must accept the **POST** method to receive the data. Example of the data sent:
```json
{
"code": "1",
"codeDescription": "Aprobada",
"auth": "123456",
"tilopayLinkId": 54421,
"orderNumber": "TPT123",
"tilopayOrderId": 12233,
"creditCardToken": "41111******11111",
"creditCardBrand": "Visa",
"last4CreditCardNumber": "1111",
"linkDescription": "Descripcion del link de pago",
"orderHash": ""
}
```
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"amount": "10",
"currency": "USD",
"reference": "123456",
"type": 0,
"description": "Description",
"client": "Client name",
"callback_url": "",
"webhook_url": ""
}
```
## Response [#respuesta]
```json
{
"type": "200",
"message": "Success",
"url": "https://app.tilopay.com/link/MjMwMjQ=",
"id": 1
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Payment link detail
> Detail of a payment link and its payments, queried by id.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/links-de-pago/detail-link-payment
```http
GET /api/v1/getDetailLinkPayment/{link_payment_id}/{api_key}
```
## What it does [#que-hace]
Returns the detail of a payment link and its associated payments. It takes no body: the data travels in the path.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Path parameters, in the order they appear in the URL:
Id of the payment link to query.
Merchant api key.
## Response [#respuesta]
```json
{
"type": "200",
"message": "Success",
"detail": {
"id": 6201,
"amount": "45.00",
"currency": "USD",
"reference": "Producto de prueba 1 TP-Shop",
"client": "NA",
"type": "Unlimited",
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
"callback_url": null,
"create": "2022-10-24 08:45:14"
},
"payments": []
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Delete a payment link
> Deletion of a payment link by id.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/links-de-pago/delete-link-payment
```http
POST /api/v1/deleteLinkPayment
```
## What it does [#que-hace]
Deletes an existing payment link.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Tilopay integration key.
Payment link id.
## Request example [#request]
The `<...>` values are placeholders: replace them with your own credentials and data.
```json
{
"key": "",
"id": "35"
}
```
## Response [#respuesta]
```json
{
"type": "200",
"status": 1,
"message": "Success"
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · List payment links
> Paginated listing of the merchant's payment links.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/links-de-pago/payment-item-list
```http
GET /api/v1/getLinkPaymentList/{api_key}/{limit}
```
## What it does [#que-hace]
Returns the paginated list of the merchant's payment links. It takes no body: the data travels in the path.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Path parameters, in the order they appear in the URL:
Merchant api key.
Number of records per page.
## Response [#respuesta]
```json
{
"type": "200",
"message": "Success",
"data": {
"current_page": 1,
"first_page_url": "http://app.tilopay.com/api/v1/getLinkPaymentList//10?page=1",
"from": 1,
"last_page": 2,
"last_page_url": "http://app.tilopay.com/api/v1/getLinkPaymentList//10?page=2",
"next_page_url": "http://app.tilopay.com/api/v1/getLinkPaymentList//10?page=2",
"path": "http://app.tilopay.com/api/v1/getLinkPaymentList//10",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 16,
"payment_link": [
{
"id": 1,
"amount": "45.00",
"currency": "USD",
"reference": "Producto de prueba 1 TP-Shop",
"url": "https://admin.tilopay.com/link/3dNjE2MA3sdd==",
"callback_url": null,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/51087219_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 2,
"amount": "35.00",
"currency": "USD",
"reference": "Producto de prueba 2",
"url": "https://admin.tilopay.com/link/dwNjE2see3MA==",
"callback_url": null,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/64156766_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 3,
"amount": "45.00",
"currency": "USD",
"reference": "Producto de prueba 3",
"url": "https://admin.tilopay.com/link/f4NjE2MwsdA==",
"callback_url": null,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/88435879_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 4,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/ceNjE2sxw2MA==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 5,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/cweNjE2Mfd5A==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 6,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/ce3NjE2fg5eMA==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 7,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/dsNjE2MAd32==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 8,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/NjE2sd32MA==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 9,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/sd3NjE2MA==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 10,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/d3dNjE2MA==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
}
]
}
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Get a payment link by id
> Query of a single payment link by its id.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api/links-de-pago/payment-by-id
```http
GET /api/v1/getLinkPaymentById/{link_payment_id}/{api_key}
```
## What it does [#que-hace]
Returns a single payment link. It takes no body: the data travels in the path.
## Authentication [#autenticacion]
Requires the API bearer token in the `Authorization` header — see [authentication](/developers/api/autenticacion).
## Parameters [#parametros]
Path parameters, in the order they appear in the URL:
Id of the payment link to query.
Merchant api key.
## Response [#respuesta]
```json
{
"type": "200",
"message": "Success",
"data": {
"id": 1,
"amount": "45.00",
"currency": "USD",
"reference": "Producto de prueba 1 TP-Shop",
"url": "https://admin.tilopay.com/link/loNj8E2MA==",
"callback_url": null,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/51087219_.png",
"create": "2022-10-24 08:45:14",
"payments": []
}
}
```
To interpret a response that is not a success, see [how to read an error response](/developers/api/procesos-operativos/errors).
---
# API · Webhooks
> Which events exist, how many retries there are, in what format they arrive and how to confirm the state of a charge.
- kind: concept
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/en/developers/api/webhooks
## Recurrence [#recurrencia]
Six fields configured when **creating or editing a plan**. All optional.
| Field | What it is |
|---|---|
| `webhook_subscribe` | Subscription webhook |
| `webhook_payment` | Charge webhook |
| `webhook_rejected` | Rejected charge webhook |
| `webhook_unsubscribe` | Unsubscribe webhook |
| `webhook_reactive` | Reactivation webhook |
| `thanks_url` | **Not a webhook:** it is a GET callback |
## Payment links [#links-de-pago]
`webhook_url` is configured when creating the link.
## Retries [#reintentos]
| Source | Attempts | When it retries |
|---|---|---|
| Recurrence | 5 | When your response is 400, 404, 502, 504 or 403 |
| Purchases | 1 | — |
Delivery is considered successful on an **HTTP 200**. Respond 200 as soon as you receive the
event and process it separately: anything else counts as a failure, and purchases have no second
attempt.
## Format [#formato]
JSON.
## The card token [#token]
| Source | Token |
|---|---|
| Recurrence | **Not sent** |
| Purchases | Sent and **usable** |
## Origin verification [#verificacion]
The only origin verification available is the `orderHash`, and **its algorithm is not public**:
it is delivered to merchants who request it by writing to `sac@tilopay.com`.
Until you have the algorithm, do not take irreversible business decisions from webhook content
alone: confirm the state against the API before shipping or releasing a service.
## Main flow webhook [#processpayment]
`processPayment` also has a webhook. Its contract **is delivered to merchants who request it**:
write to `sac@tilopay.com` to receive it.
---
# AI agents
> The three planes Tilopay offers an AI agent: reading the documentation, operating the account through the MCP server, and integrating with the API and the SDK.
- kind: guide
- status: stable
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/agentes
## Read [#leer]
The whole portal is available in machine-readable form: the
[`llms.txt`](https://www.tilopay.com/en/llms.txt) index, the raw Markdown of any URL on the site
by adding `.md`, the API [`openapi.json`](/developers/openapi.json) and the MCP server
[`mcp.json`](/developers/mcp.json).
## Act on behalf of the merchant [#actuar]
The [MCP server](/en/developers/agentes/mcp) lets an assistant operate the merchant account:
query sales, create payment links, issue refunds. Access is not self-service, and the merchant
credentials never leave the Tilopay server.
## Integrate into a product [#integrar]
When you are building a product that charges, the path is the [JavaScript SDK](/en/developers/sdk)
and the [Acquiring API](/en/developers/api/autenticacion), not the MCP.
## Which one to choose [#cual-elegir]
- Operate the account from an assistant → [MCP server](/en/developers/agentes/mcp).
- Build a product that charges → [API](/en/developers/api/autenticacion) and [SDK](/en/developers/sdk).
- Feed an agent with the documentation → [machine-readable documentation](/en/developers/agentes/documentacion-legible).
MCP access is requested through the [request form](/en/developers/agentes/mcp#solicitud).
---
# MCP server
> How access to the Tilopay MCP server is granted and how an MCP client connects with OAuth.
- kind: mcp-index
- status: stable
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/agentes/mcp
## How access is granted [#acceso]
The MCP is not self-service. The merchant sends the request with the [form below](#solicitud).
Tilopay creates a dedicated user, exclusive to this service and tied to one merchant, and
registers that merchant API credentials on the server side, encrypted. The user receives an
invitation email and sets their own password.
Three things worth knowing before requesting access:
1. The MCP user is different from the merchant API user. If you already have API credentials, you
do not reuse them here.
2. Because the user is tied to one merchant, the agent only reaches the data and the operations of
that merchant.
3. The merchant never pastes its `apiKey`, `apiUser` or `apiPassword` into the MCP client.
The merchant API credentials live encrypted on the Tilopay server and are decrypted on every
call. They are not pasted into the MCP client, nor into the assistant configuration file, and they
are never handed to the model. That is the security argument behind the whole design.
MCP usage may carry additional costs depending on the volume used. The support team shares that
detail after validating the merchant transaction volume.
## Access request [#solicitud]
The access request form lives on the HTML page: https://www.tilopay.com/en/developers/agentes/mcp — required fields are first name, last name, merchant email and merchant name. MCP usage may carry additional costs depending on the volume used.
## Connection [#conexion]
The server is `https://mcp.tilopay.com/mcp`. For an approved user:
1. Add the server in the MCP client with that URL.
2. The client discovers authentication from the 401 with `WWW-Authenticate`, which points to
`/.well-known/oauth-protected-resource`.
3. The client registers dynamically and opens the authorization screen.
4. The user signs in with their account and sees a consent screen with the application requesting
access, the return URL and the permissions.
5. On approval, the client is connected.
The model is OAuth 2.0 with `authorization_code` and `refresh_token`. The client discovers the
identity provider endpoints on its own: the only thing to configure is the server URL.
## From the most used MCP clients [#clientes]
- **Claude** (desktop and web): add a remote connector with the server URL and complete sign-in in
the window it opens.
- **ChatGPT**: add the server as a remote connector with that same URL; authorization completes in
the browser.
- **Cursor, VS Code and other editors**: declare a remote HTTP MCP server with the URL, with no
token in the configuration file; the editor opens the browser to authorize.
- **Your own client**: use an MCP client with Streamable HTTP transport and OAuth 2.0 support with
dynamic registration. The sequence is the one above: 401, discovery, registration, authorization,
connection.
The transport is Streamable HTTP. The available tools are listed by group:
[sales and transactions](/en/developers/agentes/mcp/ventas),
[payment links](/en/developers/agentes/mcp/enlaces-de-pago),
[catalog](/en/developers/agentes/mcp/catalogo),
[contacts](/en/developers/agentes/mcp/contactos) and
[support and diagnostics](/en/developers/agentes/mcp/soporte).
Before connecting an agent, read [what it can do](/en/developers/agentes/permisos).
---
# Sales and transactions
> MCP tools to query transactions, measure sales and modify a transaction.
- kind: mcp-tool
- status: stable
- access: destructive
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/agentes/mcp/ventas
## What it covers [#que-cubre]
This group covers reading transactions and analysing the merchant sales, plus modifying a transaction: capture, refund or reversal. The modification moves real money and is marked as sensitive.
## Tools [#herramientas]
### List Tilopay transactions [#tilopay-list-transactions]
- `tilopay_list_transactions`
- Access: Read only
- API operation: `POST /api/v1/consultTransactions` — https://www.tilopay.com/en/developers/api/procesos-operativos/consult-transactions
Queries Tilopay transactions in a date range. It can filter by currency, order number, customer email and environment.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `startDate` | string | yes | Start date, e.g. "2026-08-01 00:00:00" |
| `endDate` | string | yes | End date, e.g. "2026-08-31 23:59:59" |
| `onlyAproved` | boolean | — | Approved transactions only (true by default) |
| `environment` | string (production | test) | — | Environment, production by default |
| `currency` | array | — | Currencies, e.g. ["USD","CRC"] |
| `orderNumber` | string | — | Filter by order number |
| `email` | string | — | Filter by customer email |
| `limit` | integer | — | Maximum rows to return (100 by default, 500 maximum) |
**Returns**
`{ total, transactions[], environmentNote }`
total = rows found before applying limit; transactions = the rows returned; environmentNote warns when the queried environment returned no rows.
### Get one transaction [#tilopay-get-transaction]
- `tilopay_get_transaction`
- Access: Read only
- API operation: `POST /api/v1/consult` — https://www.tilopay.com/en/developers/api/procesos-operativos/consult
Returns the detail of a specific transaction from its order number.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `orderNumber` | string | yes | Order number of the transaction |
| `merchantId` | string | — | Merchant ID (optional) |
**Returns**
`{ result }`
Raw Tilopay API response under the `result` key.
### Sales summary and trends [#tilopay-sales-summary]
- `tilopay_sales_summary`
- Access: Read only
- API operation: `POST /api/v1/consultTransactions (y cálculo local)` — https://www.tilopay.com/en/developers/api/procesos-operativos/consult-transactions
Computes sales metrics from the transactions: totals by currency, average ticket, approval rate, sales by day, weekday and hour, top customers, decline reasons and trend.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `startDate` | string | yes | Start date "YYYY-MM-DD HH:mm:ss" |
| `endDate` | string | yes | End date "YYYY-MM-DD HH:mm:ss" |
| `includeDeclined` | boolean | — | Include declined transactions to measure the approval rate (true by default) |
| `environment` | string (production | test) | — | — |
| `currency` | array | — | — |
**Returns**
`{ summary, trends, environmentNote }`
summary carries range, timezoneNote, totalRows, payments {total, approved, declined, approvalRate}, refunds {total, approved, failed, successRate}, byCurrency per currency with payments, itemised costs (commission, iva_commission, cost, cost_iva, retention_iva, retention_rent, totalDeducted, taxWithholdings, pspCost), netToLiquidate, reconciles and reconciliationDelta; refunds; and netForPeriod. It also returns daily, sample, byWeekday, byHour, topCustomers, declineReasons, refundFailureReasons and transactionTypes. byWeekday, byHour and topCustomers come back null when the sample is too small (fewer than 30 rows or fewer than 5 distinct days). trends comes back null in that same case. Hours and days are in UTC.
### Sales analyst agent [#tilopay-analyze-sales]
- `tilopay_analyze_sales`
- Access: Read only
- API operation: `POST /api/v1/consultTransactions (y análisis con modelo)` — https://www.tilopay.com/en/developers/api/procesos-operativos/consult-transactions
Agent that analyses the transactions in a date range and returns a natural-language report: performance, trends, seasonality, approval quality, risks and actionable recommendations.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `startDate` | string | yes | Start date "YYYY-MM-DD HH:mm:ss" |
| `endDate` | string | yes | End date "YYYY-MM-DD HH:mm:ss" |
| `question` | string | — | Specific question or focus for the analysis |
| `environment` | string (production | test) | — | — |
| `currency` | array | — | — |
**Returns**
`{ report, summary, trends, environmentNote }`
report is the natural-language report; summary and trends are the same ones from tilopay_sales_summary. When there are no transactions in the range it returns only a text saying so, with no structuredContent.
### Capture, refund or reverse [#tilopay-modify-transaction]
- `tilopay_modify_transaction`
- Access: Sensitive
- API operation: `POST /api/v1/processModification` — https://www.tilopay.com/en/developers/api/procesos-operativos/process-modification
Modifies a transaction: capture, refund or reversal for the given amount. Sensitive operation: it moves real money.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `orderNumber` | string | yes | Order number of the transaction |
| `action` | string (capture | refund | reversal) | yes | Type of modification |
| `amount` | number | yes | Amount to modify, greater than zero |
**Returns**
`{ result }`
Raw Tilopay API response under the `result` key.
---
# Payment links
> MCP tools to create, read and delete payment links, and prepare their delivery.
- kind: mcp-tool
- status: stable
- access: destructive
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/agentes/mcp/enlaces-de-pago
## What it covers [#que-cubre]
With this group the agent creates a payment link, reads its detail, deletes it and prepares delivery to the customer over WhatsApp or email. WhatsApp delivery does not send the message: it returns a link ready to send.
## Tools [#herramientas]
### Create payment link [#tilopay-create-payment-link]
- `tilopay_create_payment_link`
- Access: Write
- API operation: `POST /api/v1/createLinkPayment` — https://www.tilopay.com/en/developers/api/links-de-pago/create-link-payment
Creates a payment link to charge a specific amount.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | number | yes | Amount to charge, greater than zero |
| `reference` | string | yes | Internal reference for the charge |
| `description` | string | yes | Description of the charge |
| `currency` | string | — | Currency, e.g. USD or CRC (USD by default) |
| `client` | string | — | Customer name |
| `client_email` | string | — | Customer email |
| `client_phone` | string | — | Customer phone |
| `type` | integer | — | Link type (0 by default) |
| `callback_url` | string | — | Return URL after the payment |
| `webhook_url` | string | — | Notification webhook URL |
**Returns**
`{ result, linkId, url }`
result is the raw response; linkId and url are the id and the URL of the link already extracted. When webhook_url is not sent, the server sets one of its own so it can report the payment.
### Payment link detail [#tilopay-get-payment-link]
- `tilopay_get_payment_link`
- Access: Read only
- API operation: `GET /api/v1/getDetailLinkPayment/{link_payment_id}/{api_key}` — https://www.tilopay.com/en/developers/api/links-de-pago/detail-link-payment
Returns the detail of a payment link by its ID.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `linkPaymentId` | string | yes | Payment link ID |
**Returns**
`{ result }`
Raw Tilopay API response under the `result` key.
### Delete payment link [#tilopay-delete-payment-link]
- `tilopay_delete_payment_link`
- Access: Sensitive
- API operation: `POST /api/v1/deleteLinkPayment` — https://www.tilopay.com/en/developers/api/links-de-pago/delete-link-payment
Deletes a payment link by its ID.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | ID of the payment link to delete |
**Returns**
`{ result }`
Raw Tilopay API response under the `result` key.
### Send payment link over WhatsApp [#tilopay-send-payment-link-whatsapp]
- `tilopay_send_payment_link_whatsapp`
- Access: Write
Prepares sending the payment link over WhatsApp: it returns a wa.me link with the message ready. It accepts the name of a saved contact or a phone number.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `link_url` | string | yes | Payment link URL |
| `contact_name` | string | — | Name of the saved contact or of the customer |
| `phone` | string | — | WhatsApp phone, e.g. +50688887777 |
| `amount` | number | — | — |
| `currency` | string | — | — |
| `description` | string | — | — |
| `message` | string | — | Your own message text |
| `save_contact` | boolean | — | Save the contact in the address book |
| `send_now` | boolean | — | Deprecated: ignored. The wa.me link is always returned. (deprecated) |
**Returns**
`{ to, message, whatsapp_url }`
It does not send the message: it returns the resolved phone, the drafted text and a wa.me link to send it with one tap. When there is no phone and no saved contact with that name, it returns an error asking for it. It saves the contact unless save_contact is false.
### Send payment link over email [#tilopay-send-payment-link-email]
- `tilopay_send_payment_link_email`
- Access: Write
Emails the payment link to the customer. It accepts the name of a saved contact or an email address.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `link_url` | string | yes | Payment link URL |
| `email` | string | — | Recipient email |
| `contact_name` | string | — | Name of the saved contact or of the customer |
| `amount` | number | — | — |
| `currency` | string | — | — |
| `description` | string | — | — |
| `message` | string | — | Additional note for the customer |
| `save_contact` | boolean | — | Save the contact in the address book |
**Returns**
`{ sent, to }`
sent is true and to is the address it was sent to. When there is no email and no saved contact with that name, it returns an error asking for it.
---
# Catalog
> MCP tools to read the merchant catalog of products and services.
- kind: mcp-tool
- status: stable
- access: read
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/agentes/mcp/catalogo
## What it covers [#que-cubre]
Read only: it lists the products or services the merchant already created as payment links and returns the detail of one.
## Tools [#herramientas]
### List catalog of products or services [#tilopay-catalog-list-items]
- `tilopay_catalog_list_items`
- Access: Read only
- API operation: `GET /api/v1/getLinkPaymentList/{api_key}/{limit}` — https://www.tilopay.com/en/developers/api/links-de-pago/payment-item-list
Lists the products or services in the payment links catalog.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | — | Maximum items (50 by default, 500 maximum) |
**Returns**
`{ result }`
Raw Tilopay API response under the `result` key.
### Catalog item detail [#tilopay-catalog-get-item]
- `tilopay_catalog_get_item`
- Access: Read only
- API operation: `GET /api/v1/getLinkPaymentById/{link_payment_id}/{api_key}` — https://www.tilopay.com/en/developers/api/links-de-pago/payment-by-id
Returns the detail of a catalog product or service by its ID.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `itemId` | string | yes | Catalog item ID |
**Returns**
`{ result }`
Raw Tilopay API response under the `result` key.
---
# Contacts
> MCP tools for the merchant address book: view, save and delete contacts.
- kind: mcp-tool
- status: stable
- access: destructive
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/agentes/mcp/contactos
## What it covers [#que-cubre]
The address book lets the agent reuse phone and email when sending a payment link, without asking again. Deleting a contact is irreversible.
## Tools [#herramientas]
### View contacts [#tilopay-list-contacts]
- `tilopay_list_contacts`
- Access: Read only
Lists the merchant's saved contacts; it can filter by name.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | — | Text to search in the name |
**Returns**
`{ contacts }`
List of the merchant's saved contacts.
### Save contact [#tilopay-save-contact]
- `tilopay_save_contact`
- Access: Write
Saves or updates a merchant contact (name, WhatsApp phone and email) to reuse it when sending links.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Contact name |
| `phone` | string | — | WhatsApp phone, e.g. +50688887777 |
| `email` | string | — | — |
| `note` | string | — | — |
**Returns**
`{ contact }`
The saved or updated contact.
### Delete contact [#tilopay-delete-contact]
- `tilopay_delete_contact`
- Access: Sensitive
Deletes a saved merchant contact by its name.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Contact name |
**Returns**
`{ removed }`
removed is true. When no contact exists with that name, it returns an error.
---
# Support and diagnostics
> MCP tools to answer with the official guides and test the API connection.
- kind: mcp-tool
- status: stable
- access: read
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/agentes/mcp/soporte
## What it covers [#que-cubre]
Two read tools: one answers dashboard usage questions with the official guides at tilopay.com/guias, and the other tests the credentials and one endpoint of each API group to know which part responds when something fails.
## Tools [#herramientas]
### Help from Tilopay guides and tutorials [#tilopay-help-guides]
- `tilopay_help_guides`
- Access: Read only
Answers questions about using the Tilopay dashboard with the official guides at tilopay.com/guias. It returns excerpts and the links to those guides.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `question` | string | yes | The merchant's question, as written |
**Returns**
`{ articles }`
Up to 3 articles with title, url and excerpt, taken from tilopay.com/guias. With no match it returns an empty articles list and a text with the available guides.
### Tilopay connection diagnostics [#tilopay-diagnostics]
- `tilopay_diagnostics`
- Access: Read only
Verifies the user credentials and tests one endpoint of each group (sales and transactions, catalog, recurring, stored cards). Useful when a tool fails, to know which part of the API is responding.
**Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `environment` | string (production | test) | — | Environment for the transactions test (production by default) |
**Returns**
`{ checks, failed }`
checks is a list with check, ok and detail for each test: credentials, transactions, catalog, recurring and stored cards. failed is the number of failing tests. Credentials come back masked.
---
# What an agent can do
> The real scope of an agent connected to the MCP server: which tools read, which tools change state, and which controls exist.
- kind: guide
- status: stable
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/agentes/permisos
## Scope of the tools [#alcance]
Of the 27 tools, 18 only read and 9 change state. 5 of those 9 are marked as sensitive.
The ones marked as sensitive are refunds and captures, charges with stored cards, deleting payment
links, deleting contacts and managing subscribers.
## Permission inheritance [#herencia-de-permisos]
The server uses the merchant API credentials, so it inherits exactly its permissions: it does not
impose additional barriers per tool. An active user can issue refunds and run bulk charges.
## Controls that do exist [#controles]
- A per-user activation switch, which cuts access without deleting the account.
- A separate administrator role, which only serves to manage users and credentials.
- A rate limit of 60 calls per minute per user.
## Human confirmation [#confirmacion-humana]
Human confirmation before a sensitive operation depends on the MCP client, not on Tilopay. Always
require it for write tools, and do not negotiate it for refunds or bulk charges.
The per-tool detail, with parameters and output, lives on each group page and in the
[`mcp.json`](/developers/mcp.json).
---
# Machine-readable documentation
> The artifacts the portal publishes for agents: llms.txt, raw Markdown on any URL, openapi.json and mcp.json.
- kind: guide
- status: stable
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/agentes/documentacion-legible
## Indexes for models [#llms]
- [www.tilopay.com/llms.txt](https://www.tilopay.com/llms.txt) — Spanish site index, with the URL and a description of every
page.
- [www.tilopay.com/llms-full.txt](https://www.tilopay.com/llms-full.txt) — the same index with the full content.
- [www.tilopay.com/en/llms.txt](https://www.tilopay.com/en/llms.txt) and [www.tilopay.com/en/llms-full.txt](https://www.tilopay.com/en/llms-full.txt) — the
English versions, with `/en` URLs.
## Raw Markdown [#markdown]
Any URL on the site returns its Markdown by adding `.md`: for example
[www.tilopay.com/en/developers/sdk/instalacion.md](https://www.tilopay.com/en/developers/sdk/instalacion.md) or
[www.tilopay.com/en/tarifas.md](https://www.tilopay.com/en/tarifas.md). It is served as `text/markdown`, with a metadata header
(page kind, status, version and last verification date). A URL that does not exist returns 404, not
HTML.
## API spec [#openapi]
- [`openapi.json`](/developers/openapi.json) — OpenAPI 3.1 spec of the Tilopay API: endpoints,
parameters, responses and examples. It is the source of truth for the API.
- [`openapi.yaml`](/developers/openapi.yaml) — the same content in YAML.
Both routes answer with `Access-Control-Allow-Origin: *`, so they can be read from the browser.
## MCP catalog [#mcp-json]
[`mcp.json`](/developers/mcp.json) describes the MCP server: its URL, the access model and the full
tool catalog with parameters, output and access level. When a tool wraps an API operation, the
entry includes that endpoint.
---
# Recipes
> Three end-to-end flows with the MCP server: charging over WhatsApp, closing the month sales and refunding with human confirmation.
- kind: guide
- status: stable
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/agentes/recetas
## Charge over WhatsApp from the catalog [#cobrar-por-whatsapp]
1. `tilopay_catalog_list_items` lists the merchant products or services.
2. `tilopay_create_payment_link` creates the link for the amount of the chosen item.
3. `tilopay_send_payment_link_whatsapp` prepares delivery to the customer.
`tilopay_send_payment_link_whatsapp` does not send the message: it returns a `wa.me` link with the
text ready to send with one tap. If there is no phone and no saved contact with that name, the tool
asks for it.
## Close the month sales [#cierre-de-mes]
1. `tilopay_sales_summary` returns totals, costs and net for the period.
2. `tilopay_analyze_sales` produces the natural-language report.
3. `tilopay_get_transaction` brings the detail of the transactions that need review.
The hours and days in the summary are in UTC, not local time. Trends and top customers come back
empty when the sample is small.
## Refund with human confirmation [#reembolso]
1. `tilopay_list_transactions` locates the transaction in the date range.
2. `tilopay_get_transaction` shows the detail to confirm it is the right one.
3. The agent asks the user for confirmation. That step is enforced by the MCP client, not by Tilopay.
4. `tilopay_modify_transaction` runs the modification with the action and the amount.
---
# Tilopay Banking API
> Tilopay's Banking-as-a-Service platform, available in Costa Rica only and with restricted access.
- kind: guide
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/en/developers/api-bancario
**Available in Costa Rica only.**
Beyond the payment gateway, Tilopay runs an independent banking API: a
Banking-as-a-Service platform that exposes SINPE operations, IBAN accounts and
collections management.
**It is a separate product.** It runs on its own infrastructure, with its own
credentials and authentication. A merchant already integrating the Tilopay payments
API does not get access to this one automatically, and the two integrations share
nothing but the brand.
## What it can do [#que-permite]
**SINPE transfers.** Sending and receiving transfers via PIN, DTR and SINPE Móvil,
with status lookup for each movement.
**Destination account validation.** Verify an account before transferring, by IBAN or
by phone number, and receive the account holder's name and the financial institution.
It lets you confirm to the user who they are paying before the money moves.
**IBAN accounts.** Balance lookup —available, booked and in-transit amounts— and
movement lookup, individually or in batch, with filters by date, status, currency and
your own reference.
**Collections management.** Validation of deposits against purchase orders, with
automatic rejection of deposits that match none, and real-time verification.
**Card issuing.** VISA or Mastercard cards, digital and physical, linked to IBAN
accounts and to the available funds.
**Notifications.** Webhooks for transfer status changes, configurable per event and
signed.
## Environments [#entornos]
The banking API has a test environment separate from production, on different hosts.
The credentials for each environment are delivered when access is enabled.
## How to get access and documentation [#acceso]
Access is restricted, granted on request, and available only for operations in Costa
Rica.
To learn about the product and request commercial access:
[baas.tilopay.com](https://baas.tilopay.com), stating estimated monthly volume, use
case and the systems to integrate.
For the detailed technical documentation —operations, parameters, response formats and
webhook contracts— write to **soporte@tilopay.com**. It is delivered together with the
credentials when access is enabled.
---