# Tilopay Portal para Desarrolladores y Agentes AI — texto completo

> Documentación técnica de Tilopay (SDK, API, webhooks, pruebas) en Markdown, sin nada normativo dentro de imágenes.

Idioma: español. Índice: https://www.tilopay.com/llms.txt

## Artefactos legibles por máquina

- [openapi.json](https://www.tilopay.com/developers/openapi.json): Spec OpenAPI 3.1 del API de Tilopay, fuente de verdad de endpoints, parámetros y respuestas.
- [mcp.json](https://www.tilopay.com/developers/mcp.json): Catálogo de las 27 herramientas del servidor MCP de Tilopay, con parámetros, salidas y nivel de acceso.

---

# Hosted payment page

> Camino de integración en el que el cliente paga en una página alojada por Tilopay y tu servidor recibe el resultado.

- kind: guide
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/hosted-payment-page

## Qué es [#que-es]

Tu servidor le pide una URL de pago al API, redirige al cliente a esa página de Tilopay y
recibe el resultado en tu callback URL.

Los datos de tarjeta se digitan en una página de Tilopay: **el comercio nunca ve un número de
tarjeta** y el servidor del comercio queda fuera de ese flujo.

Las operaciones del API de este camino están en [API · Hosted payment page](/developers/api/hosted-payment-page).

## Para quién es [#para-quien]

Para equipos que cobran con código propio pero prefieren no construir ni mantener el
formulario de tarjeta. Lo que necesitás es backend: pedir la URL y atender el callback.

## Requisitos antes de empezar [#requisitos]

1. **Credenciales propias.** No hay credenciales de sandbox compartidas: cada desarrollador
   obtiene las suyas en [registro de developer](/developers/registro).
2. **Autenticación del API.** Ver [autenticación](/developers/api/autenticacion).
3. **Una URL de callback tuya** que pueda recibir el resultado de la transacción.

## Cómo confirmar el estado de un cobro [#confirmacion]

El resultado que llega a tu callback no es la única señal disponible, y no todas las
respuestas de error viajan con un HTTP 4xx:

- Leé [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors) antes de decidir un éxito.
- Configurá [webhooks](/developers/api/webhooks) para los eventos que te interesen.
- Si una llamada falla sin respuesta clara, resolvé el estado con
  [reintentos seguros](/developers/concepts/reintentos-seguros).

## Entornos [#entornos]

Pruebas y producción comparten el mismo host. Ver
[entornos](/developers/concepts/entornos) antes de cobrar de verdad.

## Cumplimiento [#cumplimiento]

Es el camino que menos expone a tu infraestructura junto con el de sin código. Confirmá con
tu equipo de cumplimiento el alcance que aplica a tu comercio.

## Si preferís el formulario en tu sitio [#alternativa]

Usá el [SDK JavaScript](/developers/sdk): el diseño es tuyo y los datos siguen sin pasar por
tu servidor.

---

# SDK JavaScript

> Camino de integración en el que el formulario de tarjeta vive en tu página y el SDK manda los datos directo a Tilopay.

- kind: guide
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/sdk

## Qué es [#que-es]

Los campos de tarjeta viven en tu página. El SDK V2 toma control de esos inputs y manda los
datos **del navegador directo a Tilopay**: no pasan por tu servidor.

## Para quién es [#para-quien]

Para equipos que quieren controlar el diseño del checkout sin que los datos de tarjeta toquen
su backend. Necesitás frontend con JavaScript y un backend mínimo para obtener el token del
SDK.

## Cómo se arma, en orden [#orden]

1. **Credenciales.** No hay credenciales de sandbox compartidas: obtené las tuyas en
   [registro de developer](/developers/registro).
2. **Token del SDK.** Tu backend lo pide con `POST /api/v1/loginSdk`. Ver
   [autenticación](/developers/api/autenticacion).
3. **Cargá el script.** Ver [instalación](/developers/sdk/instalacion).
4. **Poné los inputs con los ids del contrato** y el contenedor `responseTilopay`. Ver
   [campos del formulario](/developers/sdk/campos-del-formulario).
5. **Iniciá la compra** con [`Tilopay.Init()`](/developers/sdk/reference/init) y mostrale al
   cliente los métodos de pago que devuelve.
6. **Cerrá la compra** con
   [`Tilopay.startPayment()`](/developers/sdk/reference/startpayment). El SDK maneja 3DS y
   renderiza el resultado en tu URL de `redirect`.

## Antes de asumir que estás en pruebas [#entornos]

Pruebas y producción comparten host: el modo se verifica con el campo `test` de `Init()`. Ver
[entornos](/developers/concepts/entornos).

## Cumplimiento [#cumplimiento]

Los datos de tarjeta no pasan por tu servidor, pero tu página los captura: consultá con tu
equipo de cumplimiento el alcance que te corresponde.

---

# API servidor a servidor (acceso restringido)

> Servicio exclusivo para comercios con certificación PCI. La URL se provisiona por comercio: no es autoservicio.

- kind: guide
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/server-to-server

<Callout type="warn">
**Acceso restringido. No es un camino de autoservicio.** No podés empezar esta integración hoy
por tu cuenta: requiere certificación PCI del comercio y una URL provisionada individualmente
por Tilopay.
</Callout>

## Qué es [#que-es]

El camino en el que los datos de tarjeta pasan por el servidor del comercio y este los envía al
API de Tilopay.

## Para quién es [#para-quien]

- Es un **servicio exclusivo para comercios que cuentan con certificación PCI**.
- La **URL es personalizada por comercio**, con una llave propia. **No es una URL pública.**

Por eso esta página no trae endpoint, ejemplos ejecutables ni cuerpos de petición: no existe una
dirección común que sirva para todos.

## Requisitos [#requisitos]

1. Certificación PCI vigente del comercio.
2. Cuenta Tilopay activa.
3. Solicitud aprobada, con la URL y la llave provisionadas por Tilopay para tu comercio.

## Cómo se solicita [#solicitud]

Escribí a `sac@tilopay.com` con el nombre del comercio y el estado de tu certificación PCI. La
URL y la llave se entregan directamente al comercio aprobado.

## Alternativas sin certificación PCI [#alternativas]

Si no tenés certificación PCI, estos caminos evitan por completo ese alcance:

- [Hosted payment page](/developers/hosted-payment-page) — Tilopay hospeda el formulario.
- [SDK JavaScript](/developers/sdk) — el formulario vive en tu página, pero los datos viajan del
  navegador directo a Tilopay.
- [Sin código](/developers/sin-codigo) — plugin o plataforma ya integrada.

---

# Entornos: pruebas y producción

> Pruebas y producción comparten host. El modo se cambia desde la cuenta y se verifica con el campo test de Init().

- kind: concept
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/concepts/entornos

<Callout type="warn">
**No existe un host de sandbox.** Pruebas y producción usan el mismo host:
`app.tilopay.com`. La URL no te dice en qué modo estás.
</Callout>

## Cómo se cambia de modo [#como-se-cambia]

El modo se alterna **desde la cuenta en el portal de Tilopay**, no desde la integración.
No hay un parámetro, un encabezado ni una URL alterna que lo cambie desde el código.

## Cómo se verifica [#como-se-verifica]

`Tilopay.Init()` devuelve un campo **`test`**:

| Valor | Significado |
|---|---|
| `0` | Producción |
| `1` | Pruebas |

Esa es la única señal disponible en tiempo de ejecución. Leela y mostrala en tu propio
checkout mientras desarrollás.

## El riesgo real [#riesgo]

<Callout type="warn">
Como el host es el mismo, un integrador puede creer que está probando y estar en
producción, cobrando de verdad. **Verificá `test` antes de asumir el modo.** Si tu
integración va a mover dinero, hacé que un `test: 0` inesperado falle ruidosamente en tus
ambientes de desarrollo.
</Callout>

---

# Reintentos seguros y orderNumber

> El API no es idempotente. Qué hacer exactamente cuando una llamada de pago se cae por timeout.

- kind: concept
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/concepts/reintentos-seguros

<Callout type="warn">
**El API de Tilopay no es idempotente.** No existe una llave de idempotencia ni un reintento
que devuelva la transacción original. Si venís de otros procesadores, este es el supuesto que
tenés que desarmar antes de escribir código.
</Callout>

## `orderNumber` es único para siempre [#ordernumber]

`orderNumber` es único por comercio **a lo largo de toda su operación**, para siempre. No se
reinicia por día, por mes ni por temporada.

Si se repite, **la nueva transacción se rechaza** con la respuesta **"Transacción
duplicada"**. No devuelve la transacción original: devuelve un rechazo.

## El problema del timeout [#timeout]

Cuando una llamada de pago se cae por red o por timeout, no sabés si la transacción se creó o
no. Y ninguna de las dos salidas intuitivas sirve:

| Qué harías | Qué pasa |
|---|---|
| Reintentar con el mismo `orderNumber` | Rechazo por duplicado, incluso si la primera sí pasó |
| Reintentar con un `orderNumber` nuevo | Riesgo de doble cobro |

**Ante un timeout de red no hay reintento seguro.**

## Qué hacer entonces [#que-hacer]

Consultá el estado antes de decidir:

1. Llamá a `POST /api/v1/consult` con el `orderNumber` original.
2. Si la transacción existe, usá su resultado. No reintentés.
3. Si no existe, ahí sí podés reintentar — y podés reusar el mismo `orderNumber`, porque no se
   consumió.

```text
pago → timeout
        │
        └─→ consult(orderNumber original)
              ├─ existe  → usar ese resultado
              └─ no existe → reintentar
```

## Consecuencias de diseño [#diseno]

- Generá el `orderNumber` en tu sistema **antes** de llamar al pago y persistilo. Si lo
  generás al vuelo, después de un timeout no tenés con qué consultar.
- Nunca derives el `orderNumber` de algo que se pueda repetir (número de carrito reciclado,
  timestamp truncado, contador reiniciable).
- Un "Transacción duplicada" no significa que el cobro falló: significa que ese
  `orderNumber` ya se usó. Consultá antes de mostrarle un error al cliente.

---

# Instalación del SDK

> La etiqueta script del SDK V2, qué versiones existen y qué garantías de versionado no hay.

- kind: guide
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/sdk/instalacion

## El script [#script]

```html
<script src="https://app.tilopay.com/sdk/v2/sdk_tpay.min.js"></script>
```

Cargalo antes de tu propio código de checkout. El SDK expone el objeto global `Tilopay`.

## jQuery no es requerido [#jquery]

<Callout type="info">
**jQuery NO es requerido.** Era un residuo del SDK V1. El artículo publicado hasta ahora
decía lo contrario y está mal: podés instalar el SDK V2 sin jQuery en la página.
</Callout>

## Versiones [#versiones]

Existen solo dos versiones:

| Versión | Estado |
|---|---|
| `v1` | Sin soporte |
| `v2` | Actual |

## Lo que no hay [#garantias]

<Callout type="warn">
**No hay versionado inmutable, no hay hash SRI y no hay changelog.** La URL
`/sdk/v2/sdk_tpay.min.js` no está anclada a una versión concreta: su contenido puede
cambiar sin aviso previo y sin una nota de cambios pública.

Consecuencias prácticas:

- No podés fijar `integrity="sha384-..."` en la etiqueta `script`, porque el archivo cambia.
- No podés depender de un número de build para reproducir un bug.
- Conviene tener pruebas de humo de tu checkout que corran periódicamente, no solo al
  desplegar.
</Callout>

## Qué sigue [#que-sigue]

- [Campos del formulario](/developers/sdk/campos-del-formulario) — los ids que el SDK busca.
- [`Tilopay.Init()`](/developers/sdk/reference/init) — iniciar la compra.

---

# Campos del formulario

> Los ids tlpy_* que el SDK V2 busca en tu formulario y el contenedor responseTilopay que necesita para 3DS.

- kind: concept
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/sdk/campos-del-formulario

El SDK V2 no renderiza el formulario: toma control de los inputs que ya existen en tu
página, buscándolos por `id`. Esos ids son un contrato — si cambiás uno, el SDK deja de
encontrar el campo.

<Callout type="info">
**El contrato son los inputs, no los contenedores.** Los `div` que envuelven a los campos
podés nombrarlos como quieras: el SDK no los busca. La única excepción es
`responseTilopay`, que sí es requerido.
</Callout>

## Campos [#campos]

<Param id="campo-tlpy-payment-method" name="tlpy_payment_method" type="text | select" required>
Contiene el id del método de pago obtenido de Tilopay. Puede estar visible u oculto, a
discreción del comercio.
</Param>

<Param id="campo-tlpy-saved-cards" name="tlpy_saved_cards" type="select" required>
Contiene el id de la tarjeta guardada obtenida de Tilopay. Si el cliente no tiene tarjetas
guardadas, ocultalo.
</Param>

<Param id="campo-tlpy-cc-number" name="tlpy_cc_number" type="text" required>
Número de tarjeta.
</Param>

<Param id="campo-tlpy-cc-expiration-date" name="tlpy_cc_expiration_date" type="text" required>
Fecha de expiración en formato mes/año, por ejemplo `01/25`.
</Param>

<Param id="campo-tlpy-cvv" name="tlpy_cvv" type="text" required>
Código de seguridad. Cuando el cliente usa una tarjeta guardada, hay que habilitar este
campo para que digite el CVV.
</Param>

<Param id="campo-response-tilopay" name="responseTilopay" type="div" required>
Contenedor requerido, **fuera del formulario**. Es donde el SDK monta el flujo 3DS.
</Param>

## El teléfono de Yappy no viaja por el DOM [#yappy]

El teléfono de Yappy **no** se toma de un campo del formulario: se envía en el parámetro
`phoneYappy` de [`Init()`](/developers/sdk/reference/init) o de
[`updateOptions()`](/developers/sdk/reference/update-options).

## Estructura de ejemplo [#estructura]

Los `div` de este ejemplo son libres; los `id` de los inputs y `responseTilopay` no.

```html
<div class="payFormTilopay">
  <select id="tlpy_payment_method" name="tlpy_payment_method"></select>

  <div>
    <select id="tlpy_saved_cards" name="tlpy_saved_cards"></select>
    <input type="text" id="tlpy_cc_number" name="tlpy_cc_number" />
    <input type="text" id="tlpy_cc_expiration_date" name="tlpy_cc_expiration_date" />
    <input type="text" id="tlpy_cvv" name="tlpy_cvv" />
  </div>
</div>

<div id="responseTilopay"></div>
```

---

# SDK · Tilopay.Init()

> Inicia una compra: autentica el checkout y devuelve los métodos de pago disponibles y las tarjetas guardadas del cliente.

- kind: sdk-method
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/sdk/reference/init

Inicia una compra. Autentica el checkout con el token del SDK y devuelve los métodos de
pago disponibles para el comercio.

Para guardar una tarjeta sin cobrarla, el SDK tiene un segundo flujo de inicio:
**`Tilopay.InitTokenize()`**, con los mismos parámetros de `Init()` excepto `amount`,
`orderNumber`, `capture` y `subscription`, que no aplican porque no se está cobrando nada.

## Firma [#firma]

```js
await Tilopay.Init({ /* parámetros */ })
```

## Parámetros [#parametros]

<Param id="init-token" name="token" type="string" required>
Token del SDK, obtenido con `POST /api/v1/loginSdk`. Ver
[autenticación](/developers/api/autenticacion).
</Param>

<Param id="init-currency" name="currency" type="string" required>
Moneda de la compra, ISO 4217.
</Param>

<Param id="init-language" name="language" type="string" required>
**Idioma** del checkout, ISO 639-1. Solo se soportan `es` y `en`; por defecto carga `es`.
</Param>

<Param id="init-amount" name="amount" type="decimal" required>
Monto de la compra.
</Param>

<Param id="init-billtoemail" name="billToEmail" type="string" required>
Correo del cliente. Es obligatorio para que la respuesta traiga las tarjetas guardadas.
</Param>

<Param id="init-ordernumber" name="orderNumber" type="string" required>
Número de orden, único por comercio. Ver
[reintentos seguros](/developers/concepts/reintentos-seguros).
</Param>

<Param id="init-typedni" name="typeDni" type="integer">
Tipo de identificación del cliente. Condicionado. Ver la
[tabla de tipos](/developers/sdk/reference/update-options#tipos-de-identificacion).
</Param>

<Param id="init-dni" name="dni" type="string">
Número de identificación del cliente. Condicionado.
</Param>

<Param id="init-billtofirstname" name="billToFirstName" type="string" required>
Nombre del cliente.
</Param>

<Param id="init-billtolastname" name="billToLastName" type="string" required>
Apellidos del cliente.
</Param>

<Param id="init-billtoaddress" name="billToAddress" type="string" required>
Dirección 1 del cliente.
</Param>

<Param id="init-billtoaddress2" name="billToAddress2" type="string">
Dirección 2 del cliente. Opcional.
</Param>

<Param id="init-billtocity" name="billToCity" type="string">
Ciudad. Recomendado.
</Param>

<Param id="init-billtostate" name="billToState" type="string">
Provincia o estado. Recomendado.
</Param>

<Param id="init-billtozippostcode" name="billToZipPostCode" type="string">
Código postal. Recomendado.
</Param>

<Param id="init-billtocountry" name="billToCountry" type="string">
País, ISO 3166-1 alpha-2. Recomendado.
</Param>

<Param id="init-billtotelephone" name="billToTelephone" type="string">
Teléfono del cliente. Recomendado.
</Param>

<Param id="init-capture" name="capture" type="integer" required>
`0` autoriza; `1` autoriza y captura.
</Param>

<Param id="init-redirect" name="redirect" type="string (URL)" required>
URL donde el SDK renderiza la respuesta final de la compra.
</Param>

<Param id="init-subscription" name="subscription" type="integer" required>
`1` guarda la tarjeta del cliente en Tilopay; `0` no la guarda.
</Param>

<Param id="init-phoneyappy" name="phoneYappy" type="string">
Teléfono Yappy. Obligatorio cuando se paga con Yappy. No se toma del DOM.
</Param>

<Param id="init-hashversion" name="hashVersion" type="string">
Opcional. Valores `"V1"` o `"V2"`. Si no se envía, el hash de la respuesta final se fabrica
con V1.
</Param>

<Param id="init-returndata" name="returnData" type="string">
Opcional. Se devuelve tal cual en la respuesta final del pago y se recupera en la URL de
respuesta de la transacción. Soporta hasta **65.535 caracteres**, aunque un valor muy
extenso puede afectar la URL de respuesta. Podés enviar un array serializado en base64 para
que cumpla el formato de string.
</Param>

## Llamada [#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,
});
```

## Respuesta [#respuesta]

<Param id="init-res-message" name="message" type="string">
`Success`, o la descripción del error.
</Param>

<Param id="init-res-test" name="test" type="integer">
`0` producción, `1` pruebas. Ver [entornos](/developers/concepts/entornos).
</Param>

<Param id="init-res-sinpemovil" name="sinpemovil" type="object">
Objeto con `code` y `amount`, presente cuando el comercio tiene SINPE Móvil. Los datos
completos, incluido el teléfono destino, se obtienen con
[`getSinpeMovil()`](/developers/sdk/reference/get-sinpe-movil).
</Param>

<Param id="init-res-methods" name="methods" type="array">
Arreglo de `{id, name, type}` con los métodos de pago disponibles.
</Param>

<Param id="init-res-cards" name="cards" type="array">
Arreglo de `{id, name, brand}` con las tarjetas guardadas del cliente.
</Param>

## Formato del id de método de pago [#formato-id-metodo]

El `id` de cada método tiene la forma `A:B:C`. **El segundo segmento define el método de
pago, y `18` corresponde a Yappy.**

## Tarjetas guardadas [#tarjetas-guardadas]

- Para que la respuesta traiga `cards` es **obligatorio enviar `billToEmail`**.
- Una vez obtenidas las tarjetas, **el correo ya no se puede cambiar** con
  [`updateOptions()`](/developers/sdk/reference/update-options).

---

# SDK · Tilopay.startPayment()

> Cierra la compra. El SDK maneja el flujo 3DS completo y renderiza la respuesta en la URL de redirect.

- kind: sdk-method
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/sdk/reference/startpayment

Cierra la compra iniciada con [`Tilopay.Init()`](/developers/sdk/reference/init).

## Firma [#firma]

```js
await Tilopay.startPayment()
```

No recibe parámetros.

## 3DS: lo maneja el SDK [#tres-ds]

**El SDK maneja todo el flujo de 3D Secure.** Lo único que tenés que hacer es asegurarte de
tener el contenedor `responseTilopay` en la página: ahí el SDK inserta lo necesario para 3DS
y conduce el proceso.

```html
<div id="responseTilopay"></div>
```

Ver [campos del formulario](/developers/sdk/campos-del-formulario#campos).

## Dónde llega el resultado [#resultado]

Al finalizar, el SDK renderiza la respuesta en la URL indicada en el parámetro `redirect` de
`Init()`. **Esa es la respuesta final de la compra**: tratá la URL de `redirect` como el punto
donde tu aplicación decide el resultado.

En caso de error, el método devuelve la descripción:

```json
{
  "message": "descripción del error"
}
```

---

# Tilopay.getCardType()

> Devuelve la marca de la tarjeta que el cliente está digitando, para mostrarle un ícono mientras escribe.

- kind: sdk-method
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/sdk/reference/get-card-type

Devuelve la marca de la tarjeta a partir del número que el cliente ya digitó en
`tlpy_cc_number`. El uso típico es mostrar el ícono de la marca mientras el cliente escribe.

## Firma [#firma]

```js
await Tilopay.getCardType()
```

No recibe parámetros.

**Precondición:** el cliente ya tiene que haber digitado el número de tarjeta.

## Llamada [#llamada]

```js
const type = await Tilopay.getCardType();
```

## Respuesta [#respuesta]

```json
{
  "message": "visa"
}
```

<Param id="get-card-type-message" name="message" type="string">
La marca de la tarjeta.
</Param>

## Marcas soportadas [#marcas-soportadas]

VISA · MASTERCARD · AMEX

Usá el resultado solo para presentación: la validación de la marca la hace Tilopay al procesar
el cobro, no este método.

---

# Tilopay.getSinpeMovil()

> Devuelve los datos que hay que mostrarle al cliente para pagar por SINPE Móvil y activa el listener del cobro.

- kind: sdk-method
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/sdk/reference/get-sinpe-movil

SINPE Móvil no se cobra desde el formulario: el cliente hace la transferencia desde su propio
banco. Este método devuelve los datos que hay que mostrarle — teléfono destino, monto exacto y
código de descripción.

## Cuándo se usa [#cuando]

Cuando el comercio tiene un método SINPE Móvil disponible y el cliente lo selecciona de la
lista que devolvió [`Init()`](/developers/sdk/reference/init).

<Callout type="info">
**No es solo un getter.** Además de devolver los datos, este método **dispara el listener de
SINPE con el backend de Tilopay**. Llamarlo es parte del flujo de cobro, no un detalle de
presentación.
</Callout>

## Firma [#firma]

```js
await Tilopay.getSinpeMovil()
```

No recibe parámetros.

**Precondiciones:**

- El cliente tiene que haber seleccionado SINPE Móvil como método de pago.
- `typeDni` y `dni` tienen que haberse enviado antes, por `Init()` o por
  [`updateOptions()`](/developers/sdk/reference/update-options).

## Llamada [#llamada]

```js
const params = await Tilopay.getSinpeMovil();
```

## Respuesta [#respuesta]

```json
{
  "message": "Success",
  "code": "863",
  "amount": 10,
  "number": "70599200"
}
```

<Param id="get-sinpe-movil-message" name="message" type="string">
`Success` cuando la operación salió bien.
</Param>

<Param id="get-sinpe-movil-code" name="code" type="string">
El código que el cliente debe escribir en la descripción de la transferencia. Es lo que permite
identificar el pago.
</Param>

<Param id="get-sinpe-movil-amount" name="amount" type="number">
El monto exacto que debe transferir.
</Param>

<Param id="get-sinpe-movil-number" name="number" type="string">
El número de teléfono destino de la transferencia.
</Param>

### En caso de error [#respuesta-de-error]

**En caso de error no devuelve nada.** No esperés un objeto con campos vacíos: tratá la
ausencia de respuesta como el caso de error.

## Qué hacer con estos datos [#que-hacer]

Al seleccionar SINPE Móvil hay que ocultar los campos de tarjeta y mostrarle al cliente estos
datos: teléfono destino, monto exacto y código para la descripción.

**No se necesita botón de pagar:** el cobro se procesa cuando llega la transferencia.

---

# Tilopay.updateOptions()

> Actualiza parcialmente los parámetros enviados a Init() cuando cambian antes de cerrar el pago.

- kind: sdk-method
- status: stable
- sdk_version: v2
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/sdk/reference/update-options

Actualiza valores que ya se habían enviado en [`Tilopay.Init()`](/developers/sdk/reference/init)
y que cambiaron durante el checkout — típicamente cuando el cliente edita sus datos, o cuando
selecciona SINPE Móvil o Yappy y hay que agregar información que antes no aplicaba.

<Callout type="info">
**Es un patch.** Se envían solo los campos que se quieren actualizar; no hay que reenviar todo.
</Callout>

## Qué significa "obligatorio" acá [#obligatorio]

En la lista de abajo, "obligatorio" significa que el campo **debe haberse enviado en `Init()` o
en `updateOptions()`**. Si no se envió en ninguno de los dos, el pago no puede avanzar. No
significa que haya que reenviarlo en cada llamada.

## Firma [#firma]

```js
await Tilopay.updateOptions({ /* solo los campos que cambian */ })
```

## Llamada [#llamada]

```js
const update = await Tilopay.updateOptions({
  typeDni: 1,
  dni: "0707770777",
  billToFirstName: "Ana",
  billToLastName: "Rojas",
});
```

## Parámetros [#parametros]

<Param id="update-options-typedni" name="typeDni" type="integer">
Tipo de identificación del cliente. Obligatorio para SINPE Móvil. Ver
[tipos de identificación](#tipos-de-identificacion).
</Param>

<Param id="update-options-dni" name="dni" type="string">
Número de identificación del cliente. Obligatorio para SINPE Móvil. **Acepta con guiones y sin
guiones.**
</Param>

<Param id="update-options-billtofirstname" name="billToFirstName" type="string" required>
Nombre del cliente.
</Param>

<Param id="update-options-billtolastname" name="billToLastName" type="string" required>
Apellidos del cliente.
</Param>

<Param id="update-options-billtoaddress" name="billToAddress" type="string" required>
Dirección 1 del cliente.
</Param>

<Param id="update-options-billtoaddress2" name="billToAddress2" type="string">
Dirección 2 del cliente. Opcional.
</Param>

<Param id="update-options-billtocity" name="billToCity" type="string">
Ciudad del cliente. Recomendado.
</Param>

<Param id="update-options-billtostate" name="billToState" type="string">
Provincia o estado. Recomendado.
</Param>

<Param id="update-options-billtozippostcode" name="billToZipPostCode" type="string">
Código postal. Recomendado.
</Param>

<Param id="update-options-billtocountry" name="billToCountry" type="string">
País, ISO 3166-1 alpha-2. Recomendado.
</Param>

<Param id="update-options-billtotelephone" name="billToTelephone" type="string">
Teléfono del cliente. Recomendado.
</Param>

<Param id="update-options-capture" name="capture" type="integer" required>
`0` autoriza; `1` autoriza y captura.
</Param>

<Param id="update-options-redirect" name="redirect" type="string (URL)" required>
URL donde se espera la respuesta final de la compra.
</Param>

<Param id="update-options-subscription" name="subscription" type="integer" required>
`1` si el cliente quiere guardar su tarjeta en Tilopay; `0` si no.
</Param>

<Param id="update-options-phoneyappy" name="phoneYappy" type="string">
Teléfono Yappy. Obligatorio cuando el cliente paga con Yappy.
</Param>

<Callout type="warn">
**`billToEmail` no se puede actualizar después de obtener las tarjetas guardadas.** Una vez que
`Init()` devolvió las tarjetas del cliente, el correo no se puede cambiar por este método.
</Callout>

## Tipos de identificación [#tipos-de-identificacion]

Aplica al parámetro `typeDni`, tanto acá como en `Tilopay.Init()`. En las máscaras, `#` es un
carácter **numérico** y `&` es **alfanumérico**. Las longitudes no cuentan los guiones.

| Código | Tipo | Formato | Longitud |
|---|---|---|---|
| 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 |

## Respuesta [#respuesta]

```json
{
  "message": "Success"
}
```

<Param id="update-options-message" name="message" type="string">
`Success` cuando la actualización salió bien; la descripción del error en caso contrario.
</Param>

---

# API · Autenticación

> Cómo obtener el token del API y el token del SDK, cuánto duran y cómo se envían en cada llamada.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/api/autenticacion

Todo el API y el SDK viven en un único host: `https://app.tilopay.com`. No hay un host
distinto para pruebas — ver [entornos](/developers/concepts/entornos).

## Las dos operaciones [#operaciones]

| Operación | Ruta | Para qué |
|---|---|---|
| Token del API | `POST /api/v1/login` | Llamadas servidor a servidor al API |
| Token del SDK | `POST /api/v1/loginSdk` | El token que se le pasa a `Tilopay.Init()` |

`loginSdk` es el método que el artículo anterior llamaba "GetTokenSdk". Es el mismo.

## Obtener el token del API [#token-api]

```bash
curl -X POST https://app.tilopay.com/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{ "apiuser": "TU_APIUSER", "password": "TU_PASSWORD" }'
```

### Cuerpo [#cuerpo]

<Param id="login-apiuser" name="apiuser" type="string" required>
Usuario de API del comercio.
</Param>

<Param id="login-password" name="password" type="string" required>
Contraseña de API del comercio.
</Param>

### Respuesta [#respuesta]

<Param id="login-access-token" name="access_token" type="string">
El token que se envía en las llamadas siguientes.
</Param>

<Param id="login-token-type" name="token_type" type="string">
Siempre `bearer`.
</Param>

<Param id="login-expires-in" name="expires_in" type="integer">
Vigencia del token. El tiempo exacto viene en esta respuesta: no lo asumás desde el
cliente.
</Param>

## Obtener el token del SDK [#token-sdk]

```bash
curl -X POST https://app.tilopay.com/api/v1/loginSdk \
  -H "Content-Type: application/json" \
  -d '{ "apiuser": "TU_APIUSER", "password": "TU_PASSWORD" }'
```

El token resultante es el que se pasa al parámetro `token` de
[`Tilopay.Init()`](/developers/sdk/reference/init).

## Vigencia [#vigencia]

- **Token del API: 24 horas.**
- **Token del SDK: 1 hora.**

El valor exacto siempre llega en `expires_in`. Cachealo del lado servidor y renovalo
cuando expire.

## Cómo se envía [#envio]

```http
Authorization: bearer <token>
```

## Revocación y límites [#revocacion]

- **Los tokens no se pueden revocar.** Si un token se filtra, no hay una operación para
  invalidarlo: hay que tratar la fuga como un incidente y rotar credenciales con Tilopay.
- **No hay límite** de tokens simultáneos por comercio. Podés pedir uno por proceso sin
  invalidar los anteriores.

## Dónde se obtienen las credenciales [#credenciales]

`apiuser`, `password` y `key` se obtienen en el panel del comercio, en
`admin.tilopay.com/admin/checkout`. Si no tenés acceso todavía, empezá por
[el registro de developer](/developers/registro).

<Callout type="warn">
Nunca pongas `apiuser` ni `password` en el navegador. El login corre en tu servidor; al
navegador solo baja el token del SDK.
</Callout>

---

# API · Obtener token del API

> Operación de login del API: devuelve el token bearer que firma el resto de las llamadas.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/autenticacion/token-api

```http
POST /api/v1/login
```

## Qué hace [#que-hace]

Devuelve el token de seguridad necesario para consumir los servicios del API. El usuario y la contraseña de API se obtienen en [Admin · Tilopay Checkout](https://admin.tilopay.com/admin/checkout).

## Autenticación [#autenticacion]

No requiere token: es la operación que lo emite. Ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="token-api-parametro-apiuser" name="apiuser" type="string">
Usuario de API del comercio, obtenido en Admin · Tilopay Checkout.
</Param>

<Param id="token-api-parametro-password" name="password" type="string">
Contraseña de API del comercio, obtenida en Admin · Tilopay Checkout.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "apiuser": "<api_user>",
  "password": "<api_password>"
}
```

## Respuesta [#respuesta]

```json
{
  "access_token": "<jwt>",
  "token_type": "bearer",
  "expires_in": 86400
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Obtener token del SDK

> Login del SDK: devuelve el token que usa Tilopay.Init() en el navegador.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/autenticacion/token-sdk

```http
POST /api/v1/loginSdk
```

## Qué hace [#que-hace]

Devuelve el token de seguridad necesario para consumir el SDK. Las tres credenciales se obtienen en [Admin · Tilopay Checkout](https://admin.tilopay.com/admin/checkout).

## Autenticación [#autenticacion]

No requiere token: es la operación que lo emite. Ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="token-sdk-parametro-apiuser" name="apiuser" type="string">
Usuario de API del comercio.
</Param>

<Param id="token-sdk-parametro-password" name="password" type="string">
Contraseña de API del comercio.
</Param>

<Param id="token-sdk-parametro-key" name="key" type="string">
Api key del comercio.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "apiuser": "<api_user>",
  "password": "<api_password>",
  "key": "<api_key>"
}
```

## Respuesta [#respuesta]

```json
{
  "access_token": "351d477adaaa51cdbb33ae4b4b8c843aa759f131c1c38415180b5035543d59d2f23f4e049706f5fa71c5f0d9ff763960a3cd035b4c1cefa428c90bedb672f780",
  "token_type": "bearer",
  "expires_in": "2023-06-05 13:32:06"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Hosted payment page

> Operaciones de hosted payment page del API de Tilopay, con parámetros y ejemplos.

- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/hosted-payment-page

## Operaciones [#operaciones]

- [processPayment](/developers/api/hosted-payment-page/process-payment)

La parte conceptual de este camino —requisitos, callback y confirmación del estado— vive en [hosted payment page](/developers/hosted-payment-page).

Todas las operaciones viven en `https://app.tilopay.com` y, salvo las de login, requieren el token del API — ver [autenticación](/developers/api/autenticacion).

---

# API · processPayment

> Parámetros, ejemplo de request y respuesta de processPayment, la operación que abre el formulario de pago.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/hosted-payment-page/process-payment

```http
POST /api/v1/processPayment
```

## Qué hace [#que-hace]

Devuelve la URL del formulario de pago para una compra.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="process-payment-parametro-redirect" name="redirect" type="string" required>
Sitio donde esperás la respuesta de la transacción, por ejemplo `mywebsite.com`. Debe soportar el método **GET**. Ejemplo de respuesta al 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`. Si `code = 1` la transacción está aprobada; en cualquier otro caso, rechazada. `OrderHash` es un string único por transacción: para usarlo del lado del comercio hay que escribir a `sac@tilopay.com` y pedir las instrucciones.
</Param>

<Param id="process-payment-parametro-key" name="key" type="string" required>
Llave relacionada con el cliente. Se obtiene en Admin · Tilopay Checkout.
</Param>

<Param id="process-payment-parametro-amount" name="amount" type="string" required>
Monto de la compra.
</Param>

<Param id="process-payment-parametro-currency" name="currency" type="string" required>
Moneda de la compra en formato ISO, por ejemplo USD, CRC, GTQ.
</Param>

<Param id="process-payment-parametro-ordernumber" name="orderNumber" type="string" required>
Número de orden, puede ser alfanumérico.
</Param>

<Param id="process-payment-parametro-capture" name="capture" type="string" required>
Captura y autoriza: 1 sí, 0 no.
</Param>

<Param id="process-payment-parametro-billtofirstname" name="billToFirstName" type="string" required>
Nombre.
</Param>

<Param id="process-payment-parametro-billtolastname" name="billToLastName" type="string" required>
Apellidos.
</Param>

<Param id="process-payment-parametro-billtoaddress" name="billToAddress" type="string" required>
Dirección.
</Param>

<Param id="process-payment-parametro-billtoaddress2" name="billToAddress2" type="string" required>
Dirección 2.
</Param>

<Param id="process-payment-parametro-billtocity" name="billToCity" type="string" required>
Ciudad.
</Param>

<Param id="process-payment-parametro-billtostate" name="billToState" type="string" required>
Estado en formato ISO, por ejemplo CR-SJ (San José, Costa Rica) o US-CA (California, EE. UU.).
</Param>

<Param id="process-payment-parametro-billtozippostcode" name="billToZipPostCode" type="string" required>
Código postal.
</Param>

<Param id="process-payment-parametro-billtocountry" name="billToCountry" type="string" required>
País en código ISO Alpha-2, por ejemplo CR (Costa Rica), US (EE. UU.) o GT (Guatemala).
</Param>

<Param id="process-payment-parametro-billtotelephone" name="billToTelephone" type="string" required>
Teléfono.
</Param>

<Param id="process-payment-parametro-billtoemail" name="billToEmail" type="string" required>
Correo del comprador.
</Param>

<Param id="process-payment-parametro-shiptofirstname" name="shipToFirstName" type="string" required>
Nombre.
</Param>

<Param id="process-payment-parametro-shiptolastname" name="shipToLastName" type="string" required>
Apellidos.
</Param>

<Param id="process-payment-parametro-shiptoaddress" name="shipToAddress" type="string" required>
Dirección.
</Param>

<Param id="process-payment-parametro-shiptoaddress2" name="shipToAddress2" type="string" required>
Dirección 2.
</Param>

<Param id="process-payment-parametro-shiptocity" name="shipToCity" type="string" required>
Ciudad.
</Param>

<Param id="process-payment-parametro-shiptostate" name="shipToState" type="string" required>
Estado en formato ISO, por ejemplo CR-SJ (San José, Costa Rica) o US-CA (California, EE. UU.).
</Param>

<Param id="process-payment-parametro-shiptozippostcode" name="shipToZipPostCode" type="string" required>
Código postal.
</Param>

<Param id="process-payment-parametro-shiptocountry" name="shipToCountry" type="string" required>
País en código ISO Alpha-2, por ejemplo CR (Costa Rica), US (EE. UU.) o GT (Guatemala).
</Param>

<Param id="process-payment-parametro-shiptotelephone" name="shipToTelephone" type="string" required>
Teléfono.
</Param>

<Param id="process-payment-parametro-subscription" name="subscription" type="string" required>
1 para forzar que el cliente guarde la tarjeta en Tilopay, 0 para no.
</Param>

<Param id="process-payment-parametro-platform" name="platform" type="string" required>
Nombre de la plataforma donde se genera la transacción.
</Param>

<Param id="process-payment-parametro-returndata" name="returnData" type="string">
Valor que Tilopay devuelve en la respuesta final. Se recomienda enviar un string en base 64.
</Param>

<Param id="process-payment-parametro-hashversion" name="hashVersion" type="string">
Solo se usa al implementar la verificación de hash. Valores posibles [V1, V2]; por defecto V1.
</Param>

<Param id="process-payment-parametro-token-version" name="token_version" type="string">
Enviar como valor "v2".
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "redirect": "https://www.urlToRedirect.com",
  "key": "<api_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"
}
```

## Respuesta [#respuesta]

```json
{
  "type": "100",
  "html": "Use url redirect",
  "url": "https://secure.tilopay.com/htmls/1212122_574572148file.html"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Procesos operativos

> Operaciones de procesos operativos del API de Tilopay, con parámetros y ejemplos.

- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/procesos-operativos

## Operaciones [#operaciones]

- [processModification](/developers/api/procesos-operativos/process-modification)
- [consult](/developers/api/procesos-operativos/consult)
- [consultTransactions](/developers/api/procesos-operativos/consult-transactions)
- [Dividir liquidación (split)](/developers/api/procesos-operativos/split)

Estas operaciones son transversales: sirven para cualquiera de los cuatro [caminos de integración](/developers), sin importar cómo se originó el cobro.

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

Todas las operaciones viven en `https://app.tilopay.com` y, salvo las de login, requieren el token del API — ver [autenticación](/developers/api/autenticacion).

---

# API · processModification

> Captura, reembolso y reverso de una transacción con processModification.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/procesos-operativos/process-modification

```http
POST /api/v1/processModification
```

## Qué hace [#que-hace]

Permite modificar una transacción ya procesada: captura, reembolso o reverso.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="process-modification-parametro-ordernumber" name="orderNumber" type="string">
Ejemplo: `1214352`
</Param>

<Param id="process-modification-parametro-type" name="type" type="string">
Ejemplo: `2`
</Param>

<Param id="process-modification-parametro-amount" name="amount" type="string">
Ejemplo: `1.00`
</Param>

<Param id="process-modification-parametro-key" name="key" type="string">
Llave relacionada con el cliente. Se obtiene en Admin · Tilopay Checkout.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "orderNumber": "1214352",
  "type": "2",
  "amount": "1.00",
  "key": "<api_key>"
}
```

## Respuesta [#respuesta-modificacion]

<Param id="modification-type" name="type" type="string">
Tipo de modificación aplicada.
</Param>

<Param id="modification-transactionid" name="transactionId" type="string">
Identificador de la transacción.
</Param>

<Param id="modification-reasoncode" name="ReasonCode" type="string">
Código de resultado de la modificación.
</Param>

<Param id="modification-reasoncodedescription" name="ReasonCodeDescription" type="string">
Texto del resultado.
</Param>

<Param id="modification-orderhash" name="OrderHash" type="string">
Hash de la orden. Ver la nota sobre `orderHash` en [webhooks](/developers/api/webhooks#verificacion).
</Param>

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · consult

> Consulta del estado y el monto procesado de una transacción puntual.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/procesos-operativos/consult

```http
POST /api/v1/consult
```

## Qué hace [#que-hace]

Consulta una transacción específica: devuelve el monto procesado y el estado de la transacción.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="consult-parametro-key" name="key" type="string">
Key de la integración Tilopay.
</Param>

<Param id="consult-parametro-ordernumber" name="orderNumber" type="string">
Número de orden consultado.
</Param>

<Param id="consult-parametro-merchantid" name="merchantId" type="string">
Id de comercio.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "orderNumber": "1212122",
  "merchantId": ""
}
```

## Respuesta [#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"
    }
  ]
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · consultTransactions

> Consulta masiva de transacciones por rango de fechas, moneda, orden o correo.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/procesos-operativos/consult-transactions

```http
POST /api/v1/consultTransactions
```

## Qué hace [#que-hace]

Consulta transacciones por rango de fechas, con filtros opcionales.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="consult-transactions-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="consult-transactions-parametro-startdate" name="startDate" type="string" required>
Fecha de inicio, formato `Y-m-d H:i:s` — por ejemplo "2022-01-15 00:00:00".
</Param>

<Param id="consult-transactions-parametro-enddate" name="endDate" type="string" required>
Fecha de fin, formato `Y-m-d H:i:s` — por ejemplo "2022-08-01 23:59:59".
</Param>

<Param id="consult-transactions-parametro-onlyaproved" name="onlyAproved" type="integer">
Indica si se obtienen solo transacciones aprobadas.

| Código | Valor |
| --- | --- |
| 0 | Cualquiera |
| 1 | Solo aprobadas |
</Param>

<Param id="consult-transactions-parametro-environment" name="environment" type="integer">
Ambiente de las transacciones a obtener.

| Código | Valor |
| --- | --- |
| 0 | Producción |
| 1 | Pruebas |
</Param>

<Param id="consult-transactions-parametro-currency" name="currency" type="array">
Array de monedas que se desean obtener, por ejemplo ["USD", "CRC"].
</Param>

<Param id="consult-transactions-parametro-merchantid" name="merchantId" type="string">
Id de comercio.
</Param>

<Param id="consult-transactions-parametro-ordernumber" name="orderNumber" type="string">
Número de orden.
</Param>

<Param id="consult-transactions-parametro-email" name="email" type="string">
Correo del cliente.
</Param>

<Param id="consult-transactions-parametro-auth" name="auth" type="string">
Número de autorización.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "startDate": "2023-06-01 00:00:00",
  "endDate": "2023-06-30 23:59:59",
  "onlyAproved": 1,
  "environment": 1,
  "currency": [
    "USD",
    "CRC"
  ],
  "merchantId": "<merchantId>",
  "orderNumber": "12135",
  "email": "customer@example.com",
  "auth": "123456"
}
```

## Respuesta [#respuesta]

```json
{
  "type": "200",
  "message": "",
  "response": [
    {
      "id": 734329,
      "orderNumber": "12135",
      "amount": "5.00",
      "taxes": "0.00",
      "discount": "0.00",
      "discount_name": "",
      "currency": "USD",
      "merchantId": "<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": "<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"
    }
  ]
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Dividir liquidación (split)

> División de la liquidación de una orden entre varios comercios facilitados.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/procesos-operativos/split

```http
POST /api/v1/orders/liquidation/split
```

## Qué hace [#que-hace]

Divide la liquidación de una orden entre varios comercios. Solo aplica a comercios que usan Tilopay como facilitador de pago, y las órdenes resultantes se identifican con el prefijo `SL|`.

Reglas:

- Los comercios deben estar aprobados y ser del mismo país.
- Si la partición es menor al monto total de la orden, el restante se le asigna al comercio que realizó la transacción original.
- Solo aplica sobre órdenes aprobadas completamente.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="split-parametro-order-id" name="order_id" type="string">
Id de la orden aprobada en Tilopay.
</Param>

<Param id="split-parametro-commerces" name="commerces" type="array">
Array asociativo con las llaves `email` y `amount` de cada comercio con el que se divide la liquidación. Incluir al comercio propietario es opcional: si no se especifica su monto, se le asigna el excedente de la partición, y si se incluye y hay excedente, se le suma.
</Param>

<Param id="split-parametro-lang" name="lang" type="string">
Idioma de la solicitud.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "order_id": "1",
  "commerces": [
    {
      "email": "commerce-1@example.com",
      "amount": "7.5"
    },
    {
      "email": "commerce-2@example.com",
      "amount": "5.5"
    }
  ],
  "lang": "en"
}
```

## Respuesta [#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": "<api_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"
      }
    ]
  }
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Cómo leer una respuesta de error

> Un HTTP 200 no significa éxito. Dónde viene el rechazo del emisor y cómo escribir el manejo de errores.

- kind: concept
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/api/procesos-operativos/errors

## El rechazo del emisor [#rechazo]

Cuando el emisor rechaza una transacción, la respuesta trae dos campos:

<Param id="error-code" name="code" type="string">
El código de rechazo del emisor.
</Param>

<Param id="error-description" name="description" type="string">
El texto del rechazo.
</Param>

## Un HTTP 200 no significa éxito [#estado-http]

<Callout type="warn">
**No hay un estándar definido de cuándo el API responde HTTP 4xx y cuándo responde HTTP 200 con
el error en el cuerpo.** Conviven las dos formas, y hay **cuatro envolturas distintas de error
según el endpoint**.

Consecuencia práctica: tu manejo de errores tiene que mirar el cuerpo siempre, no solo el
código de estado, y tolerar más de una forma de cuerpo.
</Callout>

## Cómo escribir el manejo de errores [#como-manejar]

- Tratá `code` y `description` como datos para registrar y mostrar, no como una enumeración
  sobre la que ramificar.
- No hagas `if (status === 200) éxito`. Verificá el cuerpo.
- Guardá la respuesta cruda de cada rechazo: es lo que te permite reconstruir el patrón de
  rechazos de tu comercio.
- Para decidir el estado real de una transacción después de un fallo, usá
  [reintentos seguros](/developers/concepts/reintentos-seguros).

---

# API · Recurrentes

> Operaciones de recurrentes del API de Tilopay, con parámetros y ejemplos.

- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes

## Operaciones [#operaciones]

17 operaciones en cuatro subgrupos:

- [Realizar pago](/developers/api/recurrentes/realizar-pago) — 1
- [Planes](/developers/api/recurrentes/planes) — 5
- [Suscriptores](/developers/api/recurrentes/suscriptores) — 7
- [Cupones](/developers/api/recurrentes/cupones) — 4

Todas las operaciones viven en `https://app.tilopay.com` y, salvo las de login, requieren el token del API — ver [autenticación](/developers/api/autenticacion).

---

# API · Recurrentes · Realizar pago

> Operaciones de recurrentes · realizar pago del API de Tilopay, con parámetros y ejemplos.

- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/realizar-pago

## Operaciones [#operaciones]

- [processRecurrentPayment](/developers/api/recurrentes/realizar-pago/process-recurrent-payment)

Todas las operaciones viven en `https://app.tilopay.com` y, salvo las de login, requieren el token del API — ver [autenticación](/developers/api/autenticacion).

---

# API · processRecurrentPayment

> Cobro servidor a servidor con token de tarjeta v2 mediante processRecurrentPayment.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/realizar-pago/process-recurrent-payment

```http
POST /api/v1/processRecurrentPayment
```

## Qué hace [#que-hace]

Procesa un cobro con una tarjeta ya tokenizada, sin formulario.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="process-recurrent-payment-parametro-key" name="key" type="string" required>
Llave relacionada con el cliente. Se obtiene en Admin · Tilopay Checkout.
</Param>

<Param id="process-recurrent-payment-parametro-amount" name="amount" type="string" required>
Monto de la compra.
</Param>

<Param id="process-recurrent-payment-parametro-currency" name="currency" type="string" required>
Moneda de la compra en formato ISO, por ejemplo USD, CRC, GTQ.
</Param>

<Param id="process-recurrent-payment-parametro-ordernumber" name="orderNumber" type="string" required>
Número de orden, puede ser alfanumérico.
</Param>

<Param id="process-recurrent-payment-parametro-capture" name="capture" type="string" required>
Captura y autoriza: 1 sí, 0 no.
</Param>

<Param id="process-recurrent-payment-parametro-email" name="email" type="string" required>
Correo del tarjetahabiente.
</Param>

<Param id="process-recurrent-payment-parametro-card" name="card" type="string" required>
Token de tarjeta, debe ser el token v2

- **hashVersion**: Utilizar solo en caso de implementar la verificación de hash, posibles valores [V1, V2], pod defecto se usa V1.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "amount": "10.00",
  "currency": "USD",
  "orderNumber": "1213",
  "capture": "1",
  "email": "myemail@exapmle.com",
  "card": "511111_00GOB1111"
}
```

## Respuesta [#respuesta]

```json
{
  "type": "200",
  "response": "1",
  "description": "Transacción aprobada",
  "auth": "123456",
  "tpt": 734329,
  "order_id": "12135",
  "tilopayTransaction": 734329,
  "orderHash": "f3ad85046d249bc7a781eed5285a5ded92045a2e11108063504deec72ec9b338"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Recurrentes · Planes

> Operaciones de recurrentes · planes del API de Tilopay, con parámetros y ejemplos.

- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/planes

## Operaciones [#operaciones]

- [Crear plan recurrente](/developers/api/recurrentes/planes/create-plan)
- [Editar plan recurrente](/developers/api/recurrentes/planes/edit-plan)
- [Obtener un plan recurrente](/developers/api/recurrentes/planes/get-plan)
- [Listar planes recurrentes](/developers/api/recurrentes/planes/get-plans)
- [Eliminar plan recurrente](/developers/api/recurrentes/planes/delete-plan)

Todas las operaciones viven en `https://app.tilopay.com` y, salvo las de login, requieren el token del API — ver [autenticación](/developers/api/autenticacion).

---

# API · Crear plan recurrente

> Creación de planes recurrentes: frecuencias, prueba gratis, modalidades y webhooks.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/planes/create-plan

```http
POST /api/v1/createPlanRepeat
```

## Qué hace [#que-hace]

Crea un plan de suscripción: frecuencia de cobro, moneda, periodo de prueba, modalidades y webhooks.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="create-plan-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="create-plan-parametro-title" name="title" type="string" required>
Título del plan recurrente.
</Param>

<Param id="create-plan-parametro-description" name="description" type="string">
Descripción del plan.
</Param>

<Param id="create-plan-parametro-frecuency" name="frecuency" type="integer">
Frecuencia de cobro.

| Código | Valor |
| --- | --- |
| 1 | Diario |
| 2 | Semanal |
| 3 | Mensual |
| 4 | Anual |
| 5 | Quincenal |
| 6 | Bimestral |
| 7 | Trimestral |
| 8 | Cuatrimestral |
| 9 | Semestral |
</Param>

<Param id="create-plan-parametro-currency" name="currency" type="string" required>
Código de moneda en formato ISO 4217.
</Param>

<Param id="create-plan-parametro-first-amount" name="first_amount" type="integer" required>
Monto por pago inicial.
</Param>

<Param id="create-plan-parametro-trial" name="trial" type="integer" required>
Activa el periodo de prueba gratis: 0 no, 1 sí.
</Param>

<Param id="create-plan-parametro-trial-days" name="trial_days" type="integer" required>
Días del periodo de prueba gratis.
</Param>

<Param id="create-plan-parametro-attempts" name="attempts" type="integer" required>
Cantidad de reintentos para cobros fallidos.
</Param>

<Param id="create-plan-parametro-modality" name="modality" type="array" required>
Array de modalidades del plan.
</Param>

<Param id="create-plan-parametro-thanks-url" name="thanks_url" type="string">
Campo opcional. URL de agradecimiento propia del comercio; debe soportar el método **GET**.
</Param>

<Param id="create-plan-parametro-webhook-subscribe" name="webhook_subscribe" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando un cliente adquiere una suscripción de forma exitosa. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'modality' : 'ModalityName', 'amount' : 25, 'frequency' : '', 'coupon' : '5HT5W8YT', 'free_trial' : 1, 'next_payment_date' : '2023-02-25'}`
</Param>

<Param id="create-plan-parametro-webhook-payment" name="webhook_payment" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando el cargo al cliente se realiza con éxito. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'amount' : 25, 'auth' : '123456', 'orderNumber' : 'PRE123456'}`
</Param>

<Param id="create-plan-parametro-webhook-rejected" name="webhook_rejected" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando un pago falla. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'amount' : 25}`
</Param>

<Param id="create-plan-parametro-webhook-unsubscribe" name="webhook_unsubscribe" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando un cliente cancela la suscripción a uno de sus planes. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'expire' : '2023-02-25'}`
</Param>

<Param id="create-plan-parametro-webhook-reactive" name="webhook_reactive" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando un cliente reactiva la suscripción a uno de sus planes. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'next_payment_date' : '2023-02-25'}`
</Param>

<Param id="create-plan-parametro-end-at" name="end_at" type="string">
Fecha de finalización del plan recurrente, formato `d-m-Y` (por ejemplo 25-09-2022). Si el plan no tiene fecha de fin, se envía vacío.
</Param>

<Param id="create-plan-parametro-notify" name="notify" type="integer">
En 1 agrega al correo de notificación el texto de `notify_detail` y `notify_note`. En 0 no agrega ninguno de los dos.
</Param>

<Param id="create-plan-parametro-notify-detail-es" name="notify_detail_es" type="string">
Texto del detalle en español. Opcional si `notify` es 0.
</Param>

<Param id="create-plan-parametro-notify-detail-en" name="notify_detail_en" type="string">
Texto del detalle en inglés. Opcional si `notify` es 0.
</Param>

<Param id="create-plan-parametro-notify-note-es" name="notify_note_es" type="string">
Texto de las notas en español. Opcional si `notify` es 0.
</Param>

<Param id="create-plan-parametro-notify-note-en" name="notify_note_en" type="string">
Texto de las notas en inglés. Opcional si `notify` es 0.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_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": ""
}
```

## Respuesta [#respuesta]

```json
{
  "type": "200",
  "status": 1,
  "message": "Success",
  "id": 624,
  "url": "https://app.tilopay.com/link/TmpJMHwx"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Editar plan recurrente

> Edición de un plan recurrente y de su estado.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/planes/edit-plan

```http
POST /api/v1/editPlanRepeat
```

## Qué hace [#que-hace]

Edita un plan existente, incluido su estado.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="edit-plan-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="edit-plan-parametro-id" name="id" type="integer" required>
Id del plan recurrente.
</Param>

<Param id="edit-plan-parametro-title" name="title" type="string" required>
Título del plan recurrente.
</Param>

<Param id="edit-plan-parametro-description" name="description" type="string">
Descripción del plan.
</Param>

<Param id="edit-plan-parametro-frecuency" name="frecuency" type="integer">
Frecuencia de cobro.

| Código | Valor |
| --- | --- |
| 1 | Diario |
| 2 | Semanal |
| 3 | Mensual |
| 4 | Anual |
| 5 | Quincenal |
| 6 | Bimestral |
| 7 | Trimestral |
| 8 | Cuatrimestral |
| 9 | Semestral |
</Param>

<Param id="edit-plan-parametro-currency" name="currency" type="string" required>
Código de moneda en formato ISO 4217.
</Param>

<Param id="edit-plan-parametro-first-amount" name="first_amount" type="integer" required>
Monto por pago inicial.
</Param>

<Param id="edit-plan-parametro-trial" name="trial" type="integer" required>
Activa el periodo de prueba gratis: 0 no, 1 sí.
</Param>

<Param id="edit-plan-parametro-trial-days" name="trial_days" type="integer" required>
Días del periodo de prueba gratis.
</Param>

<Param id="edit-plan-parametro-attempts" name="attempts" type="integer" required>
Cantidad de reintentos para cobros fallidos.
</Param>

<Param id="edit-plan-parametro-status" name="status" type="integer" required>
Estado del plan recurrente.

| Código | Valor |
| --- | --- |
| 0 | Inactivo |
| 1 | Activo |
| 2 | Activo pero sin registros nuevos |
</Param>

<Param id="edit-plan-parametro-thanks-url" name="thanks_url" type="string">
Campo opcional. URL de agradecimiento propia del comercio; debe soportar el método **GET**.
</Param>

<Param id="edit-plan-parametro-webhook-subscribe" name="webhook_subscribe" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando un cliente adquiere una suscripción de forma exitosa. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'modality' : 'ModalityName', 'amount' : 25, 'frequency' : '', 'coupon' : '5HT5W8YT', 'free_trial' : 1, 'next_payment_date' : '2023-02-25'}`
</Param>

<Param id="edit-plan-parametro-webhook-payment" name="webhook_payment" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando el cargo al cliente se realiza con éxito. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'amount' : 25, 'auth' : '123456', 'orderNumber' : 'PRE123456'}`
</Param>

<Param id="edit-plan-parametro-webhook-rejected" name="webhook_rejected" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando un pago falla. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'amount' : 25}`
</Param>

<Param id="edit-plan-parametro-webhook-unsubscribe" name="webhook_unsubscribe" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando un cliente cancela la suscripción a uno de sus planes. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'expire' : '2023-02-25'}`
</Param>

<Param id="edit-plan-parametro-webhook-reactive" name="webhook_reactive" type="string">
Campo opcional. URL del webhook, por método **POST**, que recibe el callback en el cuerpo de la solicitud cuando un cliente reactiva la suscripción a uno de sus planes. Ejemplo de los datos enviados: `{'id_plan' : 1, 'email' : 'email@email.com', 'next_payment_date' : '2023-02-25'}`
</Param>

<Param id="edit-plan-parametro-end-at" name="end_at" type="string">
Fecha de finalización del plan recurrente, formato `d-m-Y` (por ejemplo 25-09-2022). Si el plan no tiene fecha de fin, se envía vacío.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_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"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Obtener un plan recurrente

> Consulta de un plan recurrente por id.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/planes/get-plan

```http
POST /api/v1/getPlanRepeat
```

## Qué hace [#que-hace]

Devuelve un plan recurrente puntual.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="get-plan-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="get-plan-parametro-id" name="id" type="string" required>
Id del plan recurrente.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "id": "3"
}
```

## Respuesta [#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
  }
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Listar planes recurrentes

> Listado de los planes recurrentes de la integración.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/planes/get-plans

```http
POST /api/v1/getPlansRepeat
```

## Qué hace [#que-hace]

Devuelve los planes recurrentes del comercio.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="get-plans-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Eliminar plan recurrente

> Eliminación de un plan recurrente por id.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/planes/delete-plan

```http
POST /api/v1/deletePlanRepeat
```

## Qué hace [#que-hace]

Elimina un plan recurrente.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="delete-plan-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="delete-plan-parametro-id" name="id" type="string" required>
Id del plan recurrente.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "id": "625"
}
```

## Respuesta [#respuesta]

```json
{
  "type": "200",
  "status": 1,
  "message": "Success"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Recurrentes · Suscriptores

> Operaciones de recurrentes · suscriptores del API de Tilopay, con parámetros y ejemplos.

- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/suscriptores

## Operaciones [#operaciones]

- [Suscriptores de un plan](/developers/api/recurrentes/suscriptores/get-suscriptor-plan)
- [Editar suscriptor](/developers/api/recurrentes/suscriptores/edit-suscriptor-plan)
- [Pausar suscriptor](/developers/api/recurrentes/suscriptores/pause-suscriptor-plan)
- [Reactivar suscriptor](/developers/api/recurrentes/suscriptores/reactive-suscriptor-plan)
- [Eliminar suscriptor](/developers/api/recurrentes/suscriptores/delete-suscriptor-plan)
- [URL de registro y renovación](/developers/api/recurrentes/suscriptores/consult-url)
- [Pagos de suscriptor](/developers/api/recurrentes/suscriptores/suscriptor-payments)

Todas las operaciones viven en `https://app.tilopay.com` y, salvo las de login, requieren el token del API — ver [autenticación](/developers/api/autenticacion).

---

# API · Suscriptores de un plan

> Consulta de los suscriptores de un plan recurrente.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/suscriptores/get-suscriptor-plan

```http
POST /api/v1/getSuscriptorRepeat
```

## Qué hace [#que-hace]

Devuelve los suscriptores asociados a un plan recurrente.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="get-suscriptor-plan-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="get-suscriptor-plan-parametro-id" name="id" type="string" required>
Id del plan recurrente.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "id": "2"
}
```

## Respuesta [#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"
    }
  ]
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Editar suscriptor

> Edición del estado y la expiración de un suscriptor.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/suscriptores/edit-suscriptor-plan

```http
POST /api/v1/editSuscriptorRepeat
```

## Qué hace [#que-hace]

Cambia el estado o la fecha de expiración de un suscriptor.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="edit-suscriptor-plan-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="edit-suscriptor-plan-parametro-id" name="id" type="string" required>
Id del suscriptor.
</Param>

<Param id="edit-suscriptor-plan-parametro-status" name="status" type="string">
Estado del suscriptor.

| Código | Valor |
| --- | --- |
| 1 | Activo |
| 3 | Pausado |
| 4 | Eliminado |
</Param>

<Param id="edit-suscriptor-plan-parametro-expire" name="expire" type="string">
Fecha de expiración del plan, formato `yy-m-d`.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "id": "2",
  "status": "2",
  "expire": "2023-10-25"
}
```

## Respuesta [#respuesta]

```json
{
  "type": "200",
  "status": 1,
  "message": "Success"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Pausar suscriptor

> Pausa de la suscripción de un suscriptor.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/suscriptores/pause-suscriptor-plan

```http
POST /api/v1/pauseSuscriptorRepeat
```

## Qué hace [#que-hace]

Pausa la suscripción de un suscriptor.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="pause-suscriptor-plan-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="pause-suscriptor-plan-parametro-id-suscriptor" name="id_suscriptor" type="string" required>
Id del suscriptor.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "id_suscriptor": "1"
}
```

## Respuesta [#respuesta]

```json
{
  "type": "200",
  "status": 1,
  "message": "Success"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Reactivar suscriptor

> Reactivación de la suscripción de un suscriptor.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/suscriptores/reactive-suscriptor-plan

```http
POST /api/v1/reactiveSuscriptorRepeat
```

## Qué hace [#que-hace]

Reactiva la suscripción de un suscriptor pausado.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="reactive-suscriptor-plan-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="reactive-suscriptor-plan-parametro-id-suscriptor" name="id_suscriptor" type="string" required>
Id del suscriptor.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "id_suscriptor": "1"
}
```

## Respuesta [#respuesta]

```json
{
  "type": "200",
  "status": 1,
  "message": "Success"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Eliminar suscriptor

> Eliminación de un suscriptor de un plan recurrente.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/suscriptores/delete-suscriptor-plan

```http
POST /api/v1/deleteSuscriptorRepeat
```

## Qué hace [#que-hace]

Elimina un suscriptor de un plan recurrente.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="delete-suscriptor-plan-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="delete-suscriptor-plan-parametro-id-suscriptor" name="id_suscriptor" type="string" required>
Id del suscriptor.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "id_suscriptor": "1"
}
```

## Respuesta [#respuesta]

```json
{
  "type": "200",
  "status": 1,
  "message": "Success"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · URL de registro y renovación

> URL de registro o renovación de un plan recurrente para un correo dado.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/suscriptores/consult-url

```http
POST /api/v1/recurrentUrl
```

## Qué hace [#que-hace]

Devuelve la URL de registro de un plan recurrente para un usuario nuevo, o la URL de renovación si el correo ya está registrado.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="consult-url-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="consult-url-parametro-id" name="id" type="string" required>
Id del plan recurrente.
</Param>

<Param id="consult-url-parametro-email" name="email" type="string">
Correo del usuario para el que se quiere crear el link de registro.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "id": "1",
  "email": "email@user.com"
}
```

## Respuesta [#respuesta]

```json
{
  "type": "200",
  "message": "",
  "url_register": "https://app.tilopay.com/admin/recurrent/register/MjMy?email=email@user.com",
  "url_renew": ""
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Pagos de suscriptor

> Historial de pagos de los suscriptores de un plan recurrente.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/suscriptores/suscriptor-payments

```http
POST /api/v1/getSuscriptorPayments
```

## Qué hace [#que-hace]

Devuelve los pagos de los suscriptores de un plan recurrente.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="suscriptor-payments-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="suscriptor-payments-parametro-id" name="id" type="string" required>
Id del plan recurrente.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "id": "1"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Recurrentes · Cupones

> Operaciones de recurrentes · cupones del API de Tilopay, con parámetros y ejemplos.

- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/cupones

## Operaciones [#operaciones]

- [Crear cupón](/developers/api/recurrentes/cupones/create-coupon)
- [Listar cupones de un plan](/developers/api/recurrentes/cupones/get-coupons)
- [Obtener un cupón](/developers/api/recurrentes/cupones/get-coupon)
- [Eliminar cupón](/developers/api/recurrentes/cupones/delete-coupon)

Todas las operaciones viven en `https://app.tilopay.com` y, salvo las de login, requieren el token del API — ver [autenticación](/developers/api/autenticacion).

---

# API · Crear cupón

> Creación de cupones de descuento para planes recurrentes.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/cupones/create-coupon

```http
POST /api/v1/createCoupon
```

## Qué hace [#que-hace]

Crea un cupón de descuento para un plan recurrente: tipo de descuento, expiración, permisos de usuario y de correo, y límites de uso.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="create-coupon-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="create-coupon-parametro-planid" name="planId" type="integer" required>
Id del plan recurrente.
</Param>

<Param id="create-coupon-parametro-active-users" name="active_users" type="integer" required>
Permiso de usuarios.

| Código | Valor |
| --- | --- |
| 0 | Permitir solo usuarios nuevos |
| 1 | Permitir usuarios ya registrados |
</Param>

<Param id="create-coupon-parametro-type-discount" name="type_discount" type="integer" required>
Tipo de descuento.

| Código | Valor |
| --- | --- |
| 1 | Porcentaje |
| 2 | Monto fijo |
</Param>

<Param id="create-coupon-parametro-discount" name="discount" type="integer" required>
Valor numérico del descuento.
</Param>

<Param id="create-coupon-parametro-expire" name="expire" type="string" required>
Fecha de expiración del cupón, formato `Y-m-d` (por ejemplo 2025-10-20).
</Param>

<Param id="create-coupon-parametro-email-group" name="email_group" type="integer" required>
Permiso de correos.

| Código | Valor |
| --- | --- |
| 1 | Correos específicos |
| 2 | Cualquier correo |
</Param>

<Param id="create-coupon-parametro-email" name="email" type="string">
Lista de correos separados por coma. Requerido si `email_group` se envía en 1.
</Param>

<Param id="create-coupon-parametro-usage" name="usage" type="integer">
Cantidad total de usos.
</Param>

<Param id="create-coupon-parametro-renews" name="renews" type="integer">
Cantidad total de renovaciones válidas.
</Param>

<Param id="create-coupon-parametro-renews-by-user" name="renews_by_user" type="integer">
Total de usos por un mismo usuario.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_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
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Listar cupones de un plan

> Listado de los cupones de un plan recurrente.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/cupones/get-coupons

```http
POST /api/v1/getRepeatCoupons
```

## Qué hace [#que-hace]

Devuelve los cupones asociados a un plan recurrente.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="get-coupons-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="get-coupons-parametro-id" name="id" type="string" required>
Id del plan recurrente.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "id": "1"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Obtener un cupón

> Consulta de un cupón recurrente por id.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/cupones/get-coupon

```http
POST /api/v1/getCoupon
```

## Qué hace [#que-hace]

Devuelve un cupón puntual.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="get-coupon-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="get-coupon-parametro-id" name="id" type="string" required>
Id del cupón.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "id": "1"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Eliminar cupón

> Eliminación de un cupón recurrente por id.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/recurrentes/cupones/delete-coupon

```http
POST /api/v1/deleteCoupon
```

## Qué hace [#que-hace]

Elimina un cupón.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="delete-coupon-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="delete-coupon-parametro-id" name="id" type="string" required>
Id del cupón.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "id": "1"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Tokenización

> Operaciones de tokenización del API de Tilopay, con parámetros y ejemplos.

- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/tokenizacion

## Operaciones [#operaciones]

- [processTokenize](/developers/api/tokenizacion/process-tokenize)
- [Eliminar tarjeta](/developers/api/tokenizacion/remove-card)

Todas las operaciones viven en `https://app.tilopay.com` y, salvo las de login, requieren el token del API — ver [autenticación](/developers/api/autenticacion).

---

# API · processTokenize

> Tokenización de tarjeta con processTokenize: parámetros, request y respuesta.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/tokenizacion/process-tokenize

```http
POST /api/v1/processTokenize
```

## Qué hace [#que-hace]

Tokeniza una tarjeta: devuelve la URL del formulario de tokenización.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="process-tokenize-parametro-redirect" name="redirect" type="string">
Sitio donde espera la respuesta de la transacción.
</Param>

<Param id="process-tokenize-parametro-key" name="key" type="string">
Key asociado al comercio.
</Param>

<Param id="process-tokenize-parametro-email" name="email" type="string">
Correo electrónico del tarjetahabiente.
</Param>

<Param id="process-tokenize-parametro-language" name="language" type="string">
Idioma [es, en].
</Param>

<Param id="process-tokenize-parametro-firstname" name="firstName" type="string">
Nombre del tarjetahabiente.
</Param>

<Param id="process-tokenize-parametro-lastname" name="lastName" type="string">
Apellido del tarjetahabiente.
</Param>

<Param id="process-tokenize-parametro-token-version" name="token_version" type="string">
Enviar como valor "v2".
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "redirect": "https://urlToRedirect.com",
  "key": "<api_key>",
  "email": "email@user.com",
  "language": "es",
  "firstName": "name",
  "lastName": "lastname",
  "token_version": "v2"
}
```

## Respuesta [#respuesta]

```json
{
  "type": "100",
  "url": "https://secure.tilopay.com/htmls/TOK-5063-740506121440_1648145457file.html"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Eliminar tarjeta

> Eliminación de un token de tarjeta guardado en la bóveda privada del comercio.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/tokenizacion/remove-card

```http
POST /api/v1/user/card-remove
```

## Qué hace [#que-hace]

Elimina un token de tarjeta guardado. **Requisito:** el comercio debe contar con una bóveda de tokens privada.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="remove-card-parametro-key" name="key" type="string" required>
Llave relacionada con el comercio.
</Param>

<Param id="remove-card-parametro-email" name="email" type="string" required>
Correo del cliente asociado al token.
</Param>

<Param id="remove-card-parametro-token" name="token" type="string">
Token a eliminar.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "1234-1234-1234-1234-1234",
  "email": "email@card.com",
  "token": "411111.......1111"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Links de pago

> Operaciones de links de pago del API de Tilopay, con parámetros y ejemplos.

- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/links-de-pago

## Operaciones [#operaciones]

- [Crear link de pago](/developers/api/links-de-pago/create-link-payment)
- [Detalle de un link de pago](/developers/api/links-de-pago/detail-link-payment)
- [Eliminar un link de pago](/developers/api/links-de-pago/delete-link-payment)
- [Listar links de pago](/developers/api/links-de-pago/payment-item-list)
- [Obtener un link de pago por id](/developers/api/links-de-pago/payment-by-id)

Todas las operaciones viven en `https://app.tilopay.com` y, salvo las de login, requieren el token del API — ver [autenticación](/developers/api/autenticacion).

---

# API · Crear link de pago

> Creación de links de pago por API, con callback y webhook de respuesta.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/links-de-pago/create-link-payment

```http
POST /api/v1/createLinkPayment
```

## Qué hace [#que-hace]

Crea un link de pago con monto, moneda y comportamiento de uso.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="create-link-payment-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="create-link-payment-parametro-amount" name="amount" type="string" required>
Monto para el link de pago.
</Param>

<Param id="create-link-payment-parametro-currency" name="currency" type="string" required>
Código de moneda en formato ISO 4217.
</Param>

<Param id="create-link-payment-parametro-reference" name="reference" type="string">
Referencia del link de pago.
</Param>

<Param id="create-link-payment-parametro-type" name="type" type="integer">
Tipo de link: 0 ilimitado, 1 de un solo uso.
</Param>

<Param id="create-link-payment-parametro-description" name="description" type="string">
Descripción del pago.
</Param>

<Param id="create-link-payment-parametro-client" name="client" type="string">
Nombre del cliente, aplica solo cuando type es 1.
</Param>

<Param id="create-link-payment-parametro-callback-url" name="callback_url" type="string">
Campo opcional. URL, por método **GET**, a la que se redirige con la respuesta al completar el pago. Ejemplo de los datos enviados: `code=Val&description=Val&auth=Val&tilopayLinkId=Val&orderNumber=Val&tilopayOrderId=Val&creditCardToken=Val&creditCardBrand=Val&last4CreditCardNumber=Val&orderHash=Val`
</Param>

<Param id="create-link-payment-parametro-webhook-url" name="webhook_url" type="string">
Campo opcional. URL para enviar el webhook de respuesta al completar el pago.
Debe ser de método **POST** para que reciba los datos. Ejemplo de los datos enviados:

```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": ""
}
```
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "amount": "10",
  "currency": "USD",
  "reference": "123456",
  "type": 0,
  "description": "Description",
  "client": "Client name",
  "callback_url": "",
  "webhook_url": ""
}
```

## Respuesta [#respuesta]

```json
{
  "type": "200",
  "message": "Success",
  "url": "https://app.tilopay.com/link/MjMwMjQ=",
  "id": 1
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Detalle de un link de pago

> Detalle de un link de pago y sus pagos, consultado por id.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/links-de-pago/detail-link-payment

```http
GET /api/v1/getDetailLinkPayment/{link_payment_id}/{api_key}
```

## Qué hace [#que-hace]

Devuelve el detalle de un link de pago y sus pagos asociados. No lleva cuerpo: los datos van en la ruta.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

Parámetros de ruta, en el orden en que aparecen en la URL:

<Param id="detail-link-payment-parametro-link-payment-id" name="link_payment_id" type="string · path" required>
Id del link de pago a consultar.
</Param>

<Param id="detail-link-payment-parametro-api-key" name="api_key" type="string · path" required>
Api Key del comercio.
</Param>

## Respuesta [#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": []
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Eliminar un link de pago

> Eliminación de un link de pago por id.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/links-de-pago/delete-link-payment

```http
POST /api/v1/deleteLinkPayment
```

## Qué hace [#que-hace]

Elimina un link de pago existente.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

<Param id="delete-link-payment-parametro-key" name="key" type="string" required>
Key de la integración Tilopay.
</Param>

<Param id="delete-link-payment-parametro-id" name="id" type="string" required>
Id del link de pago.
</Param>

## Ejemplo de request [#request]

Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.

```json
{
  "key": "<api_key>",
  "id": "35"
}
```

## Respuesta [#respuesta]

```json
{
  "type": "200",
  "status": 1,
  "message": "Success"
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Listar links de pago

> Listado paginado de los links de pago del comercio.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/links-de-pago/payment-item-list

```http
GET /api/v1/getLinkPaymentList/{api_key}/{limit}
```

## Qué hace [#que-hace]

Devuelve la lista paginada de links de pago del comercio. No lleva cuerpo: los datos van en la ruta.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

Parámetros de ruta, en el orden en que aparecen en la URL:

<Param id="payment-item-list-parametro-api-key" name="api_key" type="string · path" required>
Api Key del comercio.
</Param>

<Param id="payment-item-list-parametro-limit" name="limit" type="string · path" required>
Cantidad de registros por página.
</Param>

## Respuesta [#respuesta]

```json
{
  "type": "200",
  "message": "Success",
  "data": {
    "current_page": 1,
    "first_page_url": "http://app.tilopay.com/api/v1/getLinkPaymentList/<api_key>/10?page=1",
    "from": 1,
    "last_page": 2,
    "last_page_url": "http://app.tilopay.com/api/v1/getLinkPaymentList/<api_key>/10?page=2",
    "next_page_url": "http://app.tilopay.com/api/v1/getLinkPaymentList/<api_key>/10?page=2",
    "path": "http://app.tilopay.com/api/v1/getLinkPaymentList/<api_key>/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"
      }
    ]
  }
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Obtener un link de pago por id

> Consulta de un link de pago puntual por su id.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api/links-de-pago/payment-by-id

```http
GET /api/v1/getLinkPaymentById/{link_payment_id}/{api_key}
```

## Qué hace [#que-hace]

Devuelve un link de pago puntual. No lleva cuerpo: los datos van en la ruta.

## Autenticación [#autenticacion]

Requiere el token bearer del API en el header `Authorization` — ver [autenticación](/developers/api/autenticacion).

## Parámetros [#parametros]

Parámetros de ruta, en el orden en que aparecen en la URL:

<Param id="payment-by-id-parametro-link-payment-id" name="link_payment_id" type="string · path" required>
Id del link de pago a consultar.
</Param>

<Param id="payment-by-id-parametro-api-key" name="api_key" type="string · path" required>
Api Key del comercio.
</Param>

## Respuesta [#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": []
  }
}
```

Para interpretar una respuesta que no es de éxito, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).

---

# API · Webhooks

> Qué eventos existen, cuántos reintentos hay, en qué formato llegan y cómo confirmar el estado de un cobro.

- kind: concept
- status: stable
- api_version: v1
- last_verified: 2026-08-28
- url: https://www.tilopay.com/developers/api/webhooks

## Recurrencia [#recurrencia]

Son 6 campos que se configuran al **crear o editar un plan**. Todos opcionales.

| Campo | Qué es |
|---|---|
| `webhook_subscribe` | Webhook de suscripción |
| `webhook_payment` | Webhook de cobro |
| `webhook_rejected` | Webhook de cobro rechazado |
| `webhook_unsubscribe` | Webhook de baja |
| `webhook_reactive` | Webhook de reactivación |
| `thanks_url` | **No es un webhook:** es un callback GET |

## Links de pago [#links-de-pago]

Se configura `webhook_url` al crear el link.

## Reintentos [#reintentos]

| Origen | Intentos | Cuándo reintenta |
|---|---|---|
| Recurrencia | 5 | Cuando tu respuesta es 400, 404, 502, 504 o 403 |
| Compras | 1 | — |

Se da por entregado con un **HTTP 200**. Respondé 200 en cuanto recibás el evento y procesalo
aparte: cualquier otra cosa cuenta como fallo, y en compras no hay segundo intento.

## Formato [#formato]

JSON.

## El token de tarjeta [#token]

| Origen | Token |
|---|---|
| Recurrencia | **No se envía** |
| Compras | Se envía y **es utilizable** |

## Verificación de origen [#verificacion]

<Callout type="warn">
La única verificación de origen disponible es el `orderHash`, y **su algoritmo no es público**:
se entrega al comercio que lo solicita escribiendo a `sac@tilopay.com`.

Mientras no tengás el algoritmo, no tomés decisiones de negocio irreversibles solo con el
contenido del webhook: confirmá el estado contra el API antes de despachar o liberar un
servicio.
</Callout>

## Webhook del flujo principal [#processpayment]

<Callout type="info">
`processPayment` también tiene webhook. Su contrato **se entrega al comercio que lo solicita**:
escribí a `sac@tilopay.com` para recibirlo.
</Callout>

---

# Agentes de IA

> Los tres planos que Tilopay le ofrece a un agente de IA: leer la documentación, operar la cuenta por el servidor MCP, e integrar con el API y el SDK.

- kind: guide
- status: stable
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/agentes

## Leer [#leer]

Todo el portal está disponible en formato legible por máquina: el índice
[`llms.txt`](https://www.tilopay.com/llms.txt), el Markdown crudo de cualquier URL del sitio
agregándole `.md`, el [`openapi.json`](/developers/openapi.json) del API y el
[`mcp.json`](/developers/mcp.json) del servidor MCP.

## Actuar por cuenta del comercio [#actuar]

El [servidor MCP](/developers/agentes/mcp) le permite a un asistente operar la cuenta del
comercio: consultar ventas, crear enlaces de pago, reembolsar. El acceso no es autoservicio y
las credenciales del comercio nunca salen del servidor de Tilopay.

## Integrar en producto [#integrar]

Cuando lo que se construye es un producto que cobra, el camino son el [SDK JavaScript](/developers/sdk)
y el [API Adquirencia](/developers/api/autenticacion), no el MCP.

## Cuál elegir [#cual-elegir]

- Operar la cuenta desde un asistente → [servidor MCP](/developers/agentes/mcp).
- Construir un producto que cobra → [API](/developers/api/autenticacion) y [SDK](/developers/sdk).
- Alimentar un agente con la documentación → [documentación legible](/developers/agentes/documentacion-legible).

El acceso al MCP se pide en el [formulario de solicitud](/developers/agentes/mcp#solicitud).

---

# Servidor MCP

> Cómo se obtiene el acceso al servidor MCP de Tilopay y cómo se conecta un cliente MCP con OAuth.

- kind: mcp-index
- status: stable
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/agentes/mcp

## Cómo se obtiene el acceso [#acceso]

El MCP no es autoservicio. El comercio envía la solicitud con el
[formulario de abajo](#solicitud). Tilopay crea un usuario dedicado, exclusivo para este
servicio y asociado a un comercio, y registra del lado del servidor las credenciales de API de
ese comercio, cifradas. El usuario recibe un correo de invitación y define su contraseña.

Tres cosas que conviene tener claras antes de pedir el acceso:

1. El usuario del MCP es distinto del usuario de API del comercio. Quien ya tiene credenciales
   de API no las reutiliza acá.
2. Como el usuario está asociado a un comercio, el agente sólo alcanza los datos y las
   operaciones de ese comercio.
3. El comercio nunca pega su `apiKey`, `apiUser` ni `apiPassword` en el cliente MCP.

<Callout type="warn">
Las credenciales de API del comercio viven cifradas en el servidor de Tilopay y se descifran en
cada llamada. No se pegan en el cliente MCP, ni en el archivo de configuración del asistente, ni
se le pasan al modelo. Ese es el argumento de seguridad de todo el diseño.
</Callout>

El consumo del MCP puede tener costos adicionales según el volumen utilizado. El equipo de
soporte da ese detalle después de validar el volumen transaccional del comercio.

## Solicitud de acceso [#solicitud]

El formulario de solicitud de acceso está en la página HTML: https://www.tilopay.com/developers/agentes/mcp — los campos obligatorios son nombre, apellido, correo del comercio y nombre del comercio. El consumo del MCP puede tener costos adicionales según el volumen utilizado.

## Conexión [#conexion]

El servidor es `https://mcp.tilopay.com/mcp`. Para un usuario ya aprobado:

1. Agregar el servidor en el cliente MCP con esa URL.
2. El cliente descubre la autenticación por el 401 con `WWW-Authenticate`, que apunta a
   `/.well-known/oauth-protected-resource`.
3. El cliente se registra dinámicamente y abre la pantalla de autorización.
4. El usuario inicia sesión con su cuenta y ve una pantalla de consentimiento con la aplicación
   que pide acceso, la URL de retorno y los permisos.
5. Al aprobar, el cliente queda conectado.

El modelo es OAuth 2.0 con `authorization_code` y `refresh_token`. El cliente descubre los
endpoints del proveedor de identidad por sí mismo: lo único que hay que configurar es la URL del
servidor.

## Desde los clientes MCP más usados [#clientes]

- **Claude** (escritorio y web): agregar un conector remoto con la URL del servidor y completar
  el inicio de sesión en la ventana que abre.
- **ChatGPT**: agregar el servidor como conector remoto con esa misma URL; la autorización se
  completa en el navegador.
- **Cursor, VS Code y otros editores**: declarar un servidor MCP remoto de tipo HTTP con la URL,
  sin token en el archivo de configuración; el editor abre el navegador para autorizar.
- **Cliente propio**: usar un cliente MCP con transporte Streamable HTTP y soporte de OAuth 2.0
  con registro dinámico. La secuencia es la de arriba: 401, descubrimiento, registro,
  autorización, conexión.

El transporte es Streamable HTTP. Las herramientas disponibles se listan por grupo:
[ventas y transacciones](/developers/agentes/mcp/ventas),
[enlaces de pago](/developers/agentes/mcp/enlaces-de-pago),
[catálogo](/developers/agentes/mcp/catalogo),
[contactos](/developers/agentes/mcp/contactos) y
[soporte y diagnóstico](/developers/agentes/mcp/soporte).
Antes de conectar un agente, leé [qué puede hacer](/developers/agentes/permisos).

---

# Ventas y transacciones

> Herramientas del MCP para consultar transacciones, medir ventas y modificar una transacción.

- kind: mcp-tool
- status: stable
- access: destructive
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/agentes/mcp/ventas

## Qué cubre [#que-cubre]

Este grupo cubre la lectura de transacciones y el análisis de ventas del comercio, más la modificación de una transacción: captura, reembolso o reversión. La modificación mueve dinero real y está marcada como sensible.

## Herramientas [#herramientas]

### Listar transacciones de Tilopay [#tilopay-list-transactions]

- `tilopay_list_transactions`
- Acceso: Sólo lectura
- Operación del API: `POST /api/v1/consultTransactions` — https://www.tilopay.com/developers/api/procesos-operativos/consult-transactions

Consulta las transacciones de Tilopay en un rango de fechas. Permite filtrar por moneda, número de orden, correo del cliente y ambiente.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `startDate` | string | sí | Fecha inicial, ej. "2026-08-01 00:00:00" |
| `endDate` | string | sí | Fecha final, ej. "2026-08-31 23:59:59" |
| `onlyAproved` | boolean | — | Solo transacciones aprobadas (por defecto true) |
| `environment` | string (production | test) | — | Ambiente, por defecto production |
| `currency` | array<string> | — | Monedas, ej. ["USD","CRC"] |
| `orderNumber` | string | — | Filtrar por número de orden |
| `email` | string | — | Filtrar por correo del cliente |
| `limit` | integer | — | Máximo de filas a devolver (por defecto 100, máximo 500) |

**Devuelve**

`{ total, transactions[], environmentNote }`

total = filas encontradas antes de aplicar limit; transactions = las filas devueltas; environmentNote avisa si el ambiente consultado no trajo filas.

### Consultar una transacción [#tilopay-get-transaction]

- `tilopay_get_transaction`
- Acceso: Sólo lectura
- Operación del API: `POST /api/v1/consult` — https://www.tilopay.com/developers/api/procesos-operativos/consult

Obtiene el detalle de una transacción específica a partir de su número de orden.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `orderNumber` | string | sí | Número de orden de la transacción |
| `merchantId` | string | — | ID de comercio (opcional) |

**Devuelve**

`{ result }`

Respuesta cruda del API de Tilopay bajo la llave `result`.

### Resumen y tendencias de ventas [#tilopay-sales-summary]

- `tilopay_sales_summary`
- Acceso: Sólo lectura
- Operación del API: `POST /api/v1/consultTransactions (y cálculo local)` — https://www.tilopay.com/developers/api/procesos-operativos/consult-transactions

Calcula métricas de ventas a partir de las transacciones: totales por moneda, ticket promedio, tasa de aprobación, ventas por día, día de la semana y hora, mejores clientes, motivos de rechazo y tendencia.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `startDate` | string | sí | Fecha inicial "YYYY-MM-DD HH:mm:ss" |
| `endDate` | string | sí | Fecha final "YYYY-MM-DD HH:mm:ss" |
| `includeDeclined` | boolean | — | Incluir transacciones rechazadas para medir tasa de aprobación (por defecto true) |
| `environment` | string (production | test) | — | — |
| `currency` | array<string> | — | — |

**Devuelve**

`{ summary, trends, environmentNote }`

summary trae range, timezoneNote, totalRows, payments {total, approved, declined, approvalRate}, refunds {total, approved, failed, successRate}, byCurrency por moneda con pagos, costos desglosados (commission, iva_commission, cost, cost_iva, retention_iva, retention_rent, totalDeducted, taxWithholdings, pspCost), netToLiquidate, reconciles y reconciliationDelta; reembolsos; y netForPeriod. Además daily, sample, byWeekday, byHour, topCustomers, declineReasons, refundFailureReasons y transactionTypes. byWeekday, byHour y topCustomers vienen en null si la muestra es insuficiente (menos de 30 filas o menos de 5 días distintos). trends viene en null en ese mismo caso. Las horas y días están en UTC.

### Agente analista de ventas [#tilopay-analyze-sales]

- `tilopay_analyze_sales`
- Acceso: Sólo lectura
- Operación del API: `POST /api/v1/consultTransactions (y análisis con modelo)` — https://www.tilopay.com/developers/api/procesos-operativos/consult-transactions

Agente que analiza las transacciones en un rango de fechas y devuelve un informe en lenguaje natural: desempeño, tendencias, estacionalidad, calidad de aprobación, riesgos y recomendaciones accionables.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `startDate` | string | sí | Fecha inicial "YYYY-MM-DD HH:mm:ss" |
| `endDate` | string | sí | Fecha final "YYYY-MM-DD HH:mm:ss" |
| `question` | string | — | Pregunta o enfoque específico para el análisis |
| `environment` | string (production | test) | — | — |
| `currency` | array<string> | — | — |

**Devuelve**

`{ report, summary, trends, environmentNote }`

report es el informe en lenguaje natural; summary y trends son los mismos de tilopay_sales_summary. Si no hay transacciones en el rango, devuelve solo un texto avisándolo, sin structuredContent.

### Capturar, reembolsar o reversar [#tilopay-modify-transaction]

- `tilopay_modify_transaction`
- Acceso: Sensible
- Operación del API: `POST /api/v1/processModification` — https://www.tilopay.com/developers/api/procesos-operativos/process-modification

Modifica una transacción: captura, reembolso o reversión por el monto indicado. Operación sensible: afecta dinero real.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `orderNumber` | string | sí | Número de orden de la transacción |
| `action` | string (capture | refund | reversal) | sí | Tipo de modificación |
| `amount` | number | sí | Monto a modificar, mayor que cero |

**Devuelve**

`{ result }`

Respuesta cruda del API de Tilopay bajo la llave `result`.

---

# Enlaces de pago

> Herramientas del MCP para crear, consultar y borrar enlaces de pago, y preparar su envío.

- kind: mcp-tool
- status: stable
- access: destructive
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/agentes/mcp/enlaces-de-pago

## Qué cubre [#que-cubre]

Con este grupo el agente crea un enlace de cobro, consulta su detalle, lo borra y prepara el envío al cliente por WhatsApp o por correo. El envío por WhatsApp no manda el mensaje: devuelve un enlace listo para enviar.

## Herramientas [#herramientas]

### Crear enlace de pago [#tilopay-create-payment-link]

- `tilopay_create_payment_link`
- Acceso: Escritura
- Operación del API: `POST /api/v1/createLinkPayment` — https://www.tilopay.com/developers/api/links-de-pago/create-link-payment

Crea un enlace de pago para cobrar un monto específico.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `amount` | number | sí | Monto a cobrar, mayor que cero |
| `reference` | string | sí | Referencia interna del cobro |
| `description` | string | sí | Descripción del cobro |
| `currency` | string | — | Moneda, ej. USD o CRC (por defecto USD) |
| `client` | string | — | Nombre del cliente |
| `client_email` | string | — | Correo del cliente |
| `client_phone` | string | — | Teléfono del cliente |
| `type` | integer | — | Tipo de enlace (0 por defecto) |
| `callback_url` | string | — | URL de retorno tras el pago |
| `webhook_url` | string | — | URL de webhook de notificación |

**Devuelve**

`{ result, linkId, url }`

result es la respuesta cruda; linkId y url son el id y la URL del enlace ya extraídos. Si no se envía webhook_url, el servidor pone uno propio para poder avisar cuando se pague.

### Detalle de un enlace de pago [#tilopay-get-payment-link]

- `tilopay_get_payment_link`
- Acceso: Sólo lectura
- Operación del API: `GET /api/v1/getDetailLinkPayment/{link_payment_id}/{api_key}` — https://www.tilopay.com/developers/api/links-de-pago/detail-link-payment

Obtiene el detalle de un enlace de pago por su ID.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `linkPaymentId` | string | sí | ID del enlace de pago |

**Devuelve**

`{ result }`

Respuesta cruda del API de Tilopay bajo la llave `result`.

### Eliminar enlace de pago [#tilopay-delete-payment-link]

- `tilopay_delete_payment_link`
- Acceso: Sensible
- Operación del API: `POST /api/v1/deleteLinkPayment` — https://www.tilopay.com/developers/api/links-de-pago/delete-link-payment

Elimina un enlace de pago por su ID.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | string | sí | ID del enlace de pago a eliminar |

**Devuelve**

`{ result }`

Respuesta cruda del API de Tilopay bajo la llave `result`.

### Enviar enlace de pago por WhatsApp [#tilopay-send-payment-link-whatsapp]

- `tilopay_send_payment_link_whatsapp`
- Acceso: Escritura

Prepara el envío del enlace de pago por WhatsApp: devuelve un enlace wa.me con el mensaje listo. Acepta el nombre de un contacto guardado o un teléfono.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `link_url` | string | sí | URL del enlace de pago |
| `contact_name` | string | — | Nombre del contacto guardado o del cliente |
| `phone` | string | — | Teléfono de WhatsApp, ej. +50688887777 |
| `amount` | number | — | — |
| `currency` | string | — | — |
| `description` | string | — | — |
| `message` | string | — | Texto propio del mensaje |
| `save_contact` | boolean | — | Guardar el contacto en la agenda |
| `send_now` | boolean | — | Obsoleto: se ignora. Siempre se devuelve el enlace wa.me. (obsoleto) |

**Devuelve**

`{ to, message, whatsapp_url }`

No envía el mensaje: devuelve el teléfono resuelto, el texto ya redactado y un enlace wa.me para enviarlo con un toque. Si no hay teléfono ni contacto guardado con ese nombre, devuelve error pidiéndolo. Guarda el contacto salvo que save_contact sea false.

### Enviar enlace de pago por correo [#tilopay-send-payment-link-email]

- `tilopay_send_payment_link_email`
- Acceso: Escritura

Envía el enlace de pago por correo electrónico al cliente. Acepta el nombre de un contacto guardado o un correo.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `link_url` | string | sí | URL del enlace de pago |
| `email` | string | — | Correo del destinatario |
| `contact_name` | string | — | Nombre del contacto guardado o del cliente |
| `amount` | number | — | — |
| `currency` | string | — | — |
| `description` | string | — | — |
| `message` | string | — | Nota adicional para el cliente |
| `save_contact` | boolean | — | Guardar el contacto en la agenda |

**Devuelve**

`{ sent, to }`

sent es true y to el correo al que se envió. Si no hay correo ni contacto guardado con ese nombre, devuelve error pidiéndolo.

---

# Catálogo

> Herramientas del MCP para leer el catálogo de productos y servicios del comercio.

- kind: mcp-tool
- status: stable
- access: read
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/agentes/mcp/catalogo

## Qué cubre [#que-cubre]

Sólo lectura: lista los productos o servicios que el comercio ya tiene creados en enlaces de pago y devuelve el detalle de uno.

## Herramientas [#herramientas]

### Listar catálogo de productos o servicios [#tilopay-catalog-list-items]

- `tilopay_catalog_list_items`
- Acceso: Sólo lectura
- Operación del API: `GET /api/v1/getLinkPaymentList/{api_key}/{limit}` — https://www.tilopay.com/developers/api/links-de-pago/payment-item-list

Lista los productos o servicios del catálogo de enlaces de pago.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `limit` | integer | — | Máximo de ítems (por defecto 50, máximo 500) |

**Devuelve**

`{ result }`

Respuesta cruda del API de Tilopay bajo la llave `result`.

### Detalle de un ítem del catálogo [#tilopay-catalog-get-item]

- `tilopay_catalog_get_item`
- Acceso: Sólo lectura
- Operación del API: `GET /api/v1/getLinkPaymentById/{link_payment_id}/{api_key}` — https://www.tilopay.com/developers/api/links-de-pago/payment-by-id

Obtiene el detalle de un producto o servicio del catálogo por su ID.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `itemId` | string | sí | ID del ítem del catálogo |

**Devuelve**

`{ result }`

Respuesta cruda del API de Tilopay bajo la llave `result`.

---

# Contactos

> Herramientas del MCP para la agenda del comercio: ver, guardar y borrar contactos.

- kind: mcp-tool
- status: stable
- access: destructive
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/agentes/mcp/contactos

## Qué cubre [#que-cubre]

La agenda le permite al agente reutilizar teléfono y correo al enviar un enlace de pago, sin volver a pedirlos. Borrar un contacto es irreversible.

## Herramientas [#herramientas]

### Ver contactos [#tilopay-list-contacts]

- `tilopay_list_contacts`
- Acceso: Sólo lectura

Lista los contactos guardados del comercio; opcionalmente filtra por nombre.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `search` | string | — | Texto a buscar en el nombre |

**Devuelve**

`{ contacts }`

Lista de contactos guardados del comercio.

### Guardar contacto [#tilopay-save-contact]

- `tilopay_save_contact`
- Acceso: Escritura

Guarda o actualiza un contacto del comercio (nombre, teléfono de WhatsApp y correo) para reutilizarlo en envíos.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | string | sí | Nombre del contacto |
| `phone` | string | — | Teléfono de WhatsApp, ej. +50688887777 |
| `email` | string | — | — |
| `note` | string | — | — |

**Devuelve**

`{ contact }`

El contacto guardado o actualizado.

### Eliminar contacto [#tilopay-delete-contact]

- `tilopay_delete_contact`
- Acceso: Sensible

Elimina un contacto guardado del comercio por su nombre.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | string | sí | Nombre del contacto |

**Devuelve**

`{ removed }`

removed es true. Si no existe un contacto con ese nombre, devuelve error.

---

# Soporte y diagnóstico

> Herramientas del MCP para responder con las guías oficiales y probar la conexión con el API.

- kind: mcp-tool
- status: stable
- access: read
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/agentes/mcp/soporte

## Qué cubre [#que-cubre]

Dos herramientas de lectura: una responde preguntas de uso del panel con las guías oficiales de tilopay.com/guias, y la otra prueba las credenciales y un endpoint de cada grupo del API para saber qué parte responde cuando algo falla.

## Herramientas [#herramientas]

### Ayuda con las guías y tutoriales de Tilopay [#tilopay-help-guides]

- `tilopay_help_guides`
- Acceso: Sólo lectura

Responde dudas de uso del panel de Tilopay usando las guías oficiales de tilopay.com/guias. Devuelve extractos y los enlaces a las guías.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `question` | string | sí | Pregunta del comercio, tal como la escribió |

**Devuelve**

`{ articles }`

Hasta 3 artículos con title, url y excerpt, tomados de tilopay.com/guias. Si no hay coincidencia devuelve articles vacío y un texto con las guías disponibles.

### Diagnóstico de conexión con Tilopay [#tilopay-diagnostics]

- `tilopay_diagnostics`
- Acceso: Sólo lectura

Verifica las credenciales del usuario y prueba un endpoint de cada grupo (ventas y transacciones, catálogo, recurrentes, tarjetas almacenadas). Útil cuando una herramienta falla, para saber qué parte del API responde.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `environment` | string (production | test) | — | Ambiente para la prueba de transacciones (por defecto production) |

**Devuelve**

`{ checks, failed }`

checks es una lista con check, ok y detail por cada prueba: credenciales, transacciones, catálogo, recurrentes y tarjetas almacenadas. failed es la cantidad de pruebas con error. Las credenciales se devuelven enmascaradas.

---

# Qué puede hacer un agente

> Alcance real de un agente conectado al servidor MCP: qué herramientas leen, qué herramientas modifican estado y qué controles existen.

- kind: guide
- status: stable
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/agentes/permisos

## Alcance de las herramientas [#alcance]

De las 27 herramientas, 18 sólo leen y 9 modifican estado. 5 de esas 9 están marcadas como sensibles.

Las marcadas como sensibles son reembolsos y capturas, cobros con tarjetas guardadas, borrado de
enlaces de pago, borrado de contactos y gestión de suscriptores.

## Herencia de permisos [#herencia-de-permisos]

El servidor usa las credenciales de API del comercio, así que hereda exactamente sus permisos: no
impone barreras adicionales por herramienta. Un usuario activo puede reembolsar y hacer cobros
masivos.

## Controles que existen [#controles]

- Un interruptor de activación por usuario, que corta el acceso sin borrar la cuenta.
- Un rol de administrador separado, que sólo sirve para gestionar usuarios y credenciales.
- Un límite de tasa de 60 llamadas por minuto por usuario.

## Confirmación humana [#confirmacion-humana]

<Callout type="warn">
La confirmación humana antes de una operación sensible depende del cliente MCP, no de Tilopay.
Exigila siempre para las herramientas de escritura, y no la negocies en reembolsos ni en cobros
masivos.
</Callout>

El detalle por herramienta, con parámetros y salida, está en las páginas de cada grupo y en el
[`mcp.json`](/developers/mcp.json).

---

# Documentación legible por máquina

> Los artefactos que el portal publica para agentes: llms.txt, Markdown crudo en cualquier URL, openapi.json y mcp.json.

- kind: guide
- status: stable
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/agentes/documentacion-legible

## Índices para modelos [#llms]

- [www.tilopay.com/llms.txt](https://www.tilopay.com/llms.txt) — índice del sitio en español, con la URL y una descripción
  de cada página.
- [www.tilopay.com/llms-full.txt](https://www.tilopay.com/llms-full.txt) — el mismo índice con el contenido completo.
- [www.tilopay.com/en/llms.txt](https://www.tilopay.com/en/llms.txt) y [www.tilopay.com/en/llms-full.txt](https://www.tilopay.com/en/llms-full.txt) — las
  versiones en inglés, con las URLs `/en`.

## Markdown crudo [#markdown]

Cualquier URL del sitio devuelve su Markdown agregándole `.md`: por ejemplo
[www.tilopay.com/developers/sdk/instalacion.md](https://www.tilopay.com/developers/sdk/instalacion.md) o
[www.tilopay.com/tarifas.md](https://www.tilopay.com/tarifas.md). Se sirve como `text/markdown`, con un encabezado de
metadatos (tipo de página, estado, versión y fecha de última verificación). Una URL que no existe
devuelve 404, no HTML.

## Spec del API [#openapi]

- [`openapi.json`](/developers/openapi.json) — spec OpenAPI 3.1 del API de Tilopay: endpoints,
  parámetros, respuestas y ejemplos. Es la fuente de verdad del API.
- [`openapi.yaml`](/developers/openapi.yaml) — el mismo contenido en YAML.

Las dos rutas responden con `Access-Control-Allow-Origin: *`, así que se pueden leer desde el
navegador.

## Catálogo del MCP [#mcp-json]

[`mcp.json`](/developers/mcp.json) describe el servidor MCP: su URL, el modelo de acceso y el
catálogo completo de herramientas con parámetros, salida y nivel de acceso. Cuando la herramienta
envuelve una operación del API, la entrada incluye ese endpoint.

---

# Recetas

> Tres flujos de punta a punta con el servidor MCP: cobrar por WhatsApp, cerrar las ventas del mes y reembolsar con confirmación humana.

- kind: guide
- status: stable
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/agentes/recetas

## Cobrar por WhatsApp desde el catálogo [#cobrar-por-whatsapp]

1. `tilopay_catalog_list_items` lista los productos o servicios del comercio.
2. `tilopay_create_payment_link` crea el enlace por el monto del ítem elegido.
3. `tilopay_send_payment_link_whatsapp` prepara el envío al cliente.

`tilopay_send_payment_link_whatsapp` no envía el mensaje: devuelve un enlace `wa.me` con el texto
listo para enviar con un toque. Si no hay teléfono ni contacto guardado con ese nombre, la
herramienta lo pide.

## Cerrar las ventas del mes [#cierre-de-mes]

1. `tilopay_sales_summary` devuelve los totales, costos y neto del período.
2. `tilopay_analyze_sales` produce el informe en lenguaje natural.
3. `tilopay_get_transaction` trae el detalle de las transacciones que haya que revisar.

<Callout type="warn">
Las horas y los días del resumen están en UTC, no en hora local. Las tendencias y los clientes
destacados vienen vacíos si la muestra es chica.
</Callout>

## Reembolsar con confirmación humana [#reembolso]

1. `tilopay_list_transactions` localiza la transacción en el rango de fechas.
2. `tilopay_get_transaction` muestra el detalle para confirmar que es la correcta.
3. El agente le pide confirmación al usuario. Este paso lo impone el cliente MCP, no Tilopay.
4. `tilopay_modify_transaction` ejecuta la modificación con la acción y el monto.

---

# API Bancario de Tilopay

> Plataforma de Banking-as-a-Service de Tilopay, disponible solo en Costa Rica y con acceso restringido.

- kind: guide
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://www.tilopay.com/developers/api-bancario

**Disponible únicamente en Costa Rica.**

Además de la pasarela de pagos, Tilopay opera un API bancario independiente: una
plataforma de Banking-as-a-Service que expone operaciones SINPE, cuentas IBAN y
gestión de recaudos.

**Es un producto separado.** Corre en su propia infraestructura, con credenciales y
autenticación propias. Un comercio que ya integra el API de pagos de Tilopay no
obtiene acceso a este automáticamente, y las dos integraciones no comparten nada
más que la marca.

## Qué permite hacer [#que-permite]

**Transferencias SINPE.** Envío y recepción de transferencias por PIN, DTR y SINPE
Móvil, con consulta del estado de cada movimiento.

**Validación de cuentas destino.** Verificar una cuenta antes de transferir, por IBAN
o por número de teléfono, y recibir el nombre del titular y la entidad financiera.
Sirve para confirmarle al usuario a quién le está pagando antes de mover el dinero.

**Cuentas IBAN.** Consulta de saldos —disponible, contabilizado y montos en tránsito—
y de movimientos, individualmente o por lote, con filtros por fecha, estado, moneda y
referencia propia.

**Gestión de recaudos.** Validación de depósitos contra órdenes de compra, con rechazo
automático de los depósitos que no correspondan a ninguna, y verificación en tiempo real.

**Emisión de tarjetas.** Tarjetas VISA o Mastercard, digitales y físicas, asociadas a
cuentas IBAN y a los fondos disponibles.

**Notificaciones.** Webhooks para cambios de estado de las transferencias, configurables
por evento y firmados.

## Entornos [#entornos]

El API bancario cuenta con un entorno de pruebas separado del de producción, con hosts
distintos. Las credenciales de cada entorno se entregan al momento de habilitar el acceso.

## Cómo obtener acceso y documentación [#acceso]

El acceso es restringido, se otorga por solicitud y está disponible solo para operaciones
en Costa Rica.

Para conocer el producto y solicitar acceso comercial:
[baas.tilopay.com](https://baas.tilopay.com), indicando volumen mensual estimado, caso de
uso y sistemas a integrar.

Para la documentación técnica detallada —operaciones, parámetros, formatos de respuesta y
contratos de webhook— escribí a **soporte@tilopay.com**. Se entrega junto con las
credenciales al habilitar el acceso.

---