# 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://tilopay.com/llms.txt
## Artefactos legibles por máquina
- [openapi.json](https://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://tilopay.com/developers/mcp.json): Catálogo de las herramientas del servidor MCP de Tilopay, con parámetros, salidas y nivel de acceso.
- [api-bancario/openapi.json](https://tilopay.com/developers/api-bancario/openapi.json): Spec OpenAPI 3.0.3 del API Bancario (BaaS) de Tilopay, versión 1.0.0, artefacto separado del API de adquirencia.
- [skills/index.md](https://tilopay.com/developers/skills/index.md)
- [cierre-de-caja/SKILL.md](https://tilopay.com/developers/skills/cierre-de-caja/SKILL.md)
- [cobrar-por-whatsapp/SKILL.md](https://tilopay.com/developers/skills/cobrar-por-whatsapp/SKILL.md)
- [rechazos-y-recuperacion/SKILL.md](https://tilopay.com/developers/skills/rechazos-y-recuperacion/SKILL.md)
- [conciliacion-mensual/SKILL.md](https://tilopay.com/developers/skills/conciliacion-mensual/SKILL.md)
- [cfo-de-bolsillo/SKILL.md](https://tilopay.com/developers/skills/cfo-de-bolsillo/SKILL.md)
- [catalogo-y-cobros-fijos/SKILL.md](https://tilopay.com/developers/skills/catalogo-y-cobros-fijos/SKILL.md)
---
# 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://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/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]
Usuario de API del comercio.
Contraseña de API del comercio.
### Respuesta [#respuesta]
El token que se envía en las llamadas siguientes.
Siempre `bearer`.
Vigencia del token. El tiempo exacto viene en esta respuesta: no lo asumás desde el
cliente.
## 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
```
## 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).
Nunca pongas `apiuser` ni `password` en el navegador. El login corre en tu servidor; al
navegador solo baja el token del SDK.
---
# 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://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: **vos nunca ves un número de
tarjeta** y tu servidor queda fuera de ese flujo, lo que reduce al mínimo tu alcance PCI.
La operación de este camino está en [API · processPayment](/developers/api/hosted-payment-page/process-payment).
## Diferencia con un link de pago [#diferencia-link]
- **Hosted payment page**: tu servidor pide una URL de pago por API y redirige al cliente a ella. Es ideal para flujos de checkout integrados en tu sitio o app.
- **Link de pago**: es una URL reusable que creás por API o desde el panel y compartís por mensaje, correo, redes o QR. El cliente paga cuando quiera; no necesitás redirigirlo desde tu flujo.
- En resumen: HPP para checkout integrado y transacciones puntuales; link de pago para cobros compartidos y sin desarrollo de front.
## 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/reintentos-seguros).
## Entornos [#entornos]
Pruebas y producción comparten el mismo host. Ver
[entornos](/developers/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.
---
# 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://tilopay.com/developers/entornos
**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.
## 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]
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.
## Tarjetas de prueba [#tarjetas]
En modo de pruebas se cobra con las [tarjetas de prueba](/developers/tarjetas-de-prueba):
ahí está el número, la marca, el resultado esperado y si abre la pantalla de challenge 3DS.
---
# Tarjetas de prueba
> Las 27 tarjetas del ambiente de pruebas de Tilopay, con el resultado esperado y la fricción 3DS de cada una.
- kind: guide
- status: stable
- api_version: v1
- last_verified: 2026-09-03
- url: https://tilopay.com/developers/tarjetas-de-prueba
Estas tarjetas sólo funcionan cuando la cuenta está en **modo de pruebas**. El modo se cambia
desde la cuenta y se verifica con el campo `test` que devuelve `Init()`: ver
[entornos y pruebas](/developers/entornos).
## Cómo se usan [#uso]
| Dato | Qué se ingresa |
| --- | --- |
| Fecha de vencimiento | Cualquiera en el futuro |
| CVV | Cualquiera |
| Código de la pantalla de challenge 3DS | `3ds2` |
En la pantalla de challenge 3DS el código a ingresar es **`3ds2`**. No hay otro código ni se envía
por SMS en pruebas.
## Tarjetas [#tarjetas]
La marca se deriva del prefijo: `4` Visa, `51`–`55` Mastercard, `34` American Express.
| Número | Marca | Resultado esperado | Fricción |
| --- | --- | --- | --- |
| `4111111111111111` | Visa | Aprobada | Sin fricción |
| `4012000000020089` | Visa | Aprobada | Sin fricción |
| `4012000000020006` | Visa | Aprobada | Sin fricción |
| `4012010000020088` | Visa | Aprobada | Sin fricción |
| `5100270000000072` | Mastercard | Aprobada | Sin fricción |
| `5100270000000031` | Mastercard | Aprobada | Sin fricción |
| `341111000000009` | American Express | Aprobada | Sin fricción |
| `341111000000011` | American Express | Aprobada | Sin fricción |
| `341112000000001` | American Express | Aprobada | Sin fricción |
| `341111000000037` | American Express | Aprobada | Sin fricción |
| `341112000008012` | American Express | Aprobada | Sin fricción |
| `4012000000020071` | Visa | Aprobada | Challenge 3DS |
| `4012010000020070` | Visa | Aprobada | Challenge 3DS |
| `4012010000020005` | Visa | Aprobada | Challenge 3DS |
| `5100270000000023` | Mastercard | Aprobada | Challenge 3DS |
| `5100271000000120` | Mastercard | Aprobada | Challenge 3DS |
| `4112613451591116` | Visa | Fondos insuficientes | Challenge 3DS |
| `4523080346468525` | Visa | CVV incorrecto | Sin fricción |
| `4549179990476733` | Visa | Tarjeta restringida | Sin fricción |
| `4012000000020121` | Visa | Rechazada | Sin fricción |
| `4111111111119999` | Visa | Rechazada | Sin fricción |
| `4111111111110000` | Visa | Rechazada | Sin fricción |
| `5100270000000056` | Mastercard | Rechazada | Sin fricción |
| `5111111111113333` | Mastercard | Rechazada | Sin fricción |
| `4666666666662222` | Visa | Rechazada | Sin fricción |
| `5555666666662222` | Mastercard | Rechazada | Sin fricción |
| `5100270000000098` | Mastercard | Rechazada | Challenge 3DS |
Las tarjetas con fricción **Challenge 3DS** abren la pantalla de autenticación; las de **Sin
fricción** resuelven sin pasar por ella. El resultado esperado es el mismo cada vez: la tarjeta
determina la respuesta, no el monto.
---
# 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://tilopay.com/developers/reintentos-seguros
**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.
## `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.
---
# 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://tilopay.com/developers/api/procesos-operativos/errors
## El rechazo del emisor [#rechazo]
Cuando el emisor rechaza una transacción, la respuesta trae dos campos:
El código de rechazo del emisor.
El texto del rechazo.
## Un HTTP 200 no significa éxito [#estado-http]
**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.
## 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/reintentos-seguros).
---
# API · Cuatro caminos de integración
> Los cuatro caminos para cobrar con Tilopay y la diferencia que decide cuál te conviene: por dónde viajan los datos de tarjeta.
- kind: concept
- status: stable
- api_version: v1
- last_verified: 2026-10-10
- url: https://tilopay.com/developers/api/caminos-de-integracion
## Cuatro caminos [#cuatro-caminos]
Hay cuatro formas de cobrar con Tilopay. Cambian en dos cosas: cuánto construís vos y dónde
aparecen los campos de tarjeta. Elegí una y seguí su guía; todas empiezan con tus credenciales
de sandbox, que se piden en el [registro de developer](/developers/registro).
### 1 · Sin código [#sin-codigo]
Extensiones y plugins para plataformas existentes. No escribís una línea de código.
[Ver camino](/developers/sin-codigo)
### 2 · Hosted payment page [#hosted-payment-page]
Tu servidor pide una URL al API, redirige al cliente a esa página de Tilopay y recibe el
resultado en tu callback URL.
[Ver camino](/developers/hosted-payment-page)
### 3 · SDK JavaScript [#sdk-javascript]
Los campos de tarjeta viven en tu página; el SDK los captura y los manda directo a Tilopay.
[Ver camino](/developers/sdk)
### 4 · API servidor a servidor [#servidor-a-servidor]
Acceso restringido: servicio exclusivo para comercios con certificación PCI. La URL se
provisiona por comercio, no es pública.
[Requisitos y solicitud](/developers/server-to-server)
## Cómo elegir [#como-elegir]
Elegir mal sale caro. La diferencia que más importa es por dónde viajan los datos de tarjeta.
| Camino | Quién construye el formulario | Por dónde viajan los datos de tarjeta | Qué se necesita saber | Implicación de cumplimiento |
| --- | --- | --- | --- | --- |
| 1 · Sin código | La plataforma | Nunca pasan por tus sistemas | Configuración en el panel de la plataforma | Consultá con tu equipo de cumplimiento |
| 2 · Hosted payment page | Tilopay | Tu cliente los digita en una página segura de Tilopay; vos nunca ves un número de tarjeta | Backend: pedir la URL y recibir el callback | Consultá con tu equipo de cumplimiento |
| 3 · SDK JavaScript | Tu sitio | Se digitan en tu página pero viajan del navegador directo a Tilopay; no pasan por tu servidor | Frontend con JavaScript, más backend para credenciales | Consultá con tu equipo de cumplimiento |
| 4 · Servidor a servidor (acceso restringido) | Tu sitio | Los datos de tarjeta pasan por tu servidor | Requiere tu certificación PCI y URL provisionada por Tilopay | Consultá con tu equipo de cumplimiento |
El camino 4 no es de autoservicio: es exclusivo para comercios con certificación PCI y la URL
se provisiona individualmente. Además es el único que mete a tu servidor dentro del alcance de
PCI DSS. Los caminos 2 y 3 evitan ese costo y podés empezarlos hoy.
## Después de elegir [#despues-de-elegir]
Con el camino elegido, seguí con [convenciones de las respuestas](/developers/api/convenciones)
para saber cómo vienen tipados los montos, y con [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors)
antes de poner el código en producción.
---
# API · Convenciones de las respuestas
> Cómo vienen tipados los montos, dónde hay JSON dentro de una cadena y por qué la misma entidad cambia de forma entre consultar uno y listar.
- kind: concept
- status: stable
- api_version: v1
- last_verified: 2026-09-02
- url: https://tilopay.com/developers/api/convenciones
Las respuestas del API de adquirencia tienen tres detalles que no se deducen leyendo cada
operación por separado y que rompen integraciones tipadas. Están acá porque aplican a
varias operaciones a la vez.
Para el manejo de errores, ver [cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).
## Los montos vienen como cadena, no como número [#montos-cadena]
Los montos, descuentos e importes se serializan como cadena: `"discount": "40.00"`,
`"amount": "0.00"`, `"first_amount": "0.00"`, `"amount_max_daily": "1000.00"`.
Cualquier deserialización tipada que declare esos campos como número falla. Declaralos
como cadena y convertilos vos, con el tipo decimal de tu lenguaje, no con punto flotante.
Aparece, entre otras, en [obtener un cupón](/developers/api/recurrentes/cupones/get-coupon),
[listar cupones](/developers/api/recurrentes/cupones/get-coupons),
[listar planes](/developers/api/recurrentes/planes/get-plans) y
[pagos de suscriptor](/developers/api/recurrentes/suscriptores/suscriptor-payments).
## Hay un JSON dentro de una cadena [#doble-encoding]
En [pagos de suscriptor](/developers/api/recurrentes/suscriptores/suscriptor-payments), el
campo `data` de cada pago **no es un objeto: es una cadena que contiene JSON**.
```json
"data": "{\"first\":1,\"expire\":\"2024-12-28T19:05:29.572648Z\",\"amount\":0,\"activeAmount\":0,\"originalAmount\":0,\"key\":\"XXXX-XXXX-XXXX-XXXX-XXXX\"}"
```
Hay que deserializar dos veces: primero la respuesta, después el contenido de `data`.
Tratá esa segunda deserialización como puede fallar cualquier entrada externa: envolvela y
registrá la cadena cruda si no parsea.
## La misma entidad cambia de forma entre "obtener uno" y "listar" [#uno-vs-lista]
No es un descuido de la documentación: las dos operaciones devuelven formas distintas del
mismo cupón, y hay que mapearlas por separado.
| | [`getCoupon`](/developers/api/recurrentes/cupones/get-coupon) (uno) | [`getRepeatCoupons`](/developers/api/recurrentes/cupones/get-coupons) (lista) |
| --- | --- | --- |
| Fecha de creación | `created_at`, formato ISO | `create`, formato `Y-m-d H:i:s` |
| Otros campos | incluye `recurrent_id`, `updated_at` y `deleted_at` | no los incluye |
Lo mismo pasa en
[pagos de suscriptor](/developers/api/recurrentes/suscriptores/suscriptor-payments), que
también usa `create` con formato `Y-m-d H:i:s`.
## Dos formas de decir "no configurado" [#no-configurado]
En [listar planes](/developers/api/recurrentes/planes/get-plans), los campos de webhook de
un plan vienen como cadena vacía cuando no están configurados, mientras que `return_url`
viene como `null`. Son dos representaciones del mismo estado en el mismo objeto: al
verificar si un webhook está configurado, tratá la cadena vacía y `null` como el mismo
caso.
---
# 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://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]
Usuario de API del comercio, obtenido en Admin · Tilopay Checkout.
Contraseña de API del comercio, obtenida en Admin · Tilopay Checkout.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"apiuser": "",
"password": ""
}
```
## Respuesta [#respuesta]
```json
{
"access_token": "",
"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).
---
# Hosted payment page
> 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://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]
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 `soporte@tilopay.com` y pedir las instrucciones.
Llave relacionada con el cliente. Se obtiene en Admin · Tilopay Checkout.
Monto de la compra.
Moneda de la compra en formato ISO, por ejemplo USD, CRC, GTQ.
Número de orden, puede ser alfanumérico.
Captura y autoriza: 1 sí, 0 no.
Nombre.
Apellidos.
Dirección.
Dirección 2.
Ciudad.
Estado en formato ISO, por ejemplo CR-SJ (San José, Costa Rica) o US-CA (California, EE. UU.).
Código postal.
País en código ISO Alpha-2, por ejemplo CR (Costa Rica), US (EE. UU.) o GT (Guatemala).
Teléfono.
Correo del comprador.
Nombre.
Apellidos.
Dirección.
Dirección 2.
Ciudad.
Estado en formato ISO, por ejemplo CR-SJ (San José, Costa Rica) o US-CA (California, EE. UU.).
Código postal.
País en código ISO Alpha-2, por ejemplo CR (Costa Rica), US (EE. UU.) o GT (Guatemala).
Teléfono.
1 para forzar que el cliente guarde la tarjeta en Tilopay, 0 para no.
Nombre de la plataforma donde se genera la transacción.
Valor que Tilopay devuelve en la respuesta final. Se recomienda enviar un string en base 64.
Solo se usa al implementar la verificación de hash. Valores posibles [V1, V2]; por defecto V1.
Enviar como valor "v2".
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"redirect": "https://www.urlToRedirect.com",
"key": "",
"amount": "1.00",
"currency": "USD",
"orderNumber": "1212122",
"capture": "1",
"billToFirstName": "DEMO",
"billToLastName": "DEMO",
"billToAddress": "San Jose",
"billToAddress2": "Catedral",
"billToCity": "JS",
"billToState": "SJ",
"billToZipPostCode": "10061",
"billToCountry": "CR",
"billToTelephone": "88888888",
"billToEmail": "cliente@ejemplo.com",
"shipToFirstName": "DEMO",
"shipToLastName": "DEMO",
"shipToAddress": "San Jose",
"shipToAddress2": "Catedral",
"shipToCity": "JS",
"shipToState": "SJ",
"shipToZipPostCode": "10061",
"shipToCountry": "CR",
"shipToTelephone": "88888888",
"subscription": "0",
"platform": "api",
"returnData": "dXNlcl9pZD0xMg==",
"hashVersion": "V2",
"token_version": "v2"
}
```
## 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).
---
# Servidor a servidor
> 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://tilopay.com/developers/server-to-server
**Acceso restringido. No es un camino de autoservicio.** No podés empezar esta integración hoy
por tu cuenta: requiere que tu empresa tenga certificación PCI y una URL provisionada individualmente
por Tilopay.
## Qué es [#que-es]
El camino en el que los datos de tarjeta pasan por tu servidor 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 los ejemplos de esta página no traen una URL real: el `Host` y la llave del proxy se
entregan a cada comercio aprobado.
## Requisitos [#requisitos]
1. Certificación PCI vigente de tu empresa.
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 `soporte@tilopay.com` con el nombre de tu comercio y el estado de tu certificación PCI. La
URL y la llave se entregan directamente al comercio aprobado.
## Referencia de la petición [#referencia]
El `Host` y el header `tx-proxy-key` los entrega Tilopay a cada comercio aprobado. No hay una URL
pública: los ejemplos usan marcadores.
```http
POST / HTTP/1.1
Host: url provided by tilopay
```
### Encabezados [#encabezados]
`bearer {token del API}` — ver [autenticación](/developers/api/autenticacion).
Llave del proxy de transacciones, provista por Tilopay.
### Parámetros [#parametros]
Llave relacionada con el comercio (obligatorio).
Número de tarjeta (obligatorio).
Código de seguridad (obligatorio).
Fecha de expiración en formato mesAño, por ejemplo `1023` (obligatorio).
Nombre del tarjetahabiente (requerido).
Apellidos del tarjetahabiente (requerido).
Teléfono del cliente (requerido).
Correo del cliente (obligatorio).
Dirección del cliente (requerido).
Ciudad del cliente (requerido).
Estado en formato ISO, por ejemplo `CR-SJ` (San José, Costa Rica) o `US-CA` (California, EEUU) (requerido).
Código postal (requerido).
País en código ISO Alpha-2, por ejemplo `CR`, `US`, `GT` (requerido).
Monto de la compra (obligatorio).
Moneda en formato ISO, por ejemplo `USD`, `CRC`, `GTQ` (obligatorio).
Número de orden (obligatorio).
`1` captura y autoriza, `0` solo autoriza (obligatorio).
URL de respuesta (obligatorio).
Los campos `shipTo*` (`shipToFirstName`, `shipToLastName`, `shipToAddress`, `shipToAddress2`,
`shipToCity`, `shipToState`, `shipToZipPostCode`, `shipToCountry`, `shipToTelephone`) aparecen en los
ejemplos de la colección como datos de envío.
### Petición [#peticion]
```json
{
"key": "key",
"card": "card PAN",
"cvv": "CVV Number",
"expire": "1023",
"name": "firstname",
"lastname": "lastname",
"phone": "88888888",
"email": "email@user.com",
"address": "user address",
"city": "city",
"state": "state",
"zipcode": "zipcode",
"country": "country",
"shipToFirstName": "Nombre",
"shipToLastName": "Apellido",
"shipToAddress": "San Jose",
"shipToAddress2": "Escazu",
"shipToCity": "San Jose",
"shipToState": "SJ",
"shipToZipPostCode": "10101",
"shipToCountry": "CR",
"shipToTelephone": "88778877",
"amount": "amount",
"currency": "currency code",
"orderNumber": "Order Number",
"capture": 1,
"redirect": "url to redirect"
}
```
La colección incluye dos ejemplos, **con 3DS** y **sin 3DS**, con el mismo cuerpo de petición.
### Respuesta [#respuesta]
```json
{
"code": "1",
"description": "Transaccion aprobada",
"auth": "123456",
"orderNumber": "12345",
"urlRedirect": "",
"error": ""
}
```
Cuando la transacción requiere autenticación 3DS, la respuesta trae la URL en `urlRedirect`; ahí es
donde se envía al tarjetahabiente. Para interpretar `code`, `description` y `error`, ver
[convenciones de las respuestas](/developers/api/convenciones) y
[cómo leer una respuesta de error](/developers/api/procesos-operativos/errors).
## 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.
---
# 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://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://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]
Key de la integración Tilopay.
Monto para el link de pago.
Código de moneda en formato ISO 4217.
Referencia del link de pago.
Tipo de link: 0 ilimitado, 1 de un solo uso.
Descripción del pago.
Nombre del cliente, aplica solo cuando type es 1.
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`
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": ""
}
```
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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:
Id del link de pago a consultar.
Api Key del comercio.
## 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://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]
Key de la integración Tilopay.
Id del link de pago.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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:
Api Key del comercio.
Cantidad de registros por página.
## Respuesta [#respuesta]
```json
{
"type": "200",
"message": "Success",
"data": {
"current_page": 1,
"first_page_url": "http://app.tilopay.com/api/v1/getLinkPaymentList//10?page=1",
"from": 1,
"last_page": 2,
"last_page_url": "http://app.tilopay.com/api/v1/getLinkPaymentList//10?page=2",
"next_page_url": "http://app.tilopay.com/api/v1/getLinkPaymentList//10?page=2",
"path": "http://app.tilopay.com/api/v1/getLinkPaymentList//10",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 16,
"payment_link": [
{
"id": 1,
"amount": "45.00",
"currency": "USD",
"reference": "Producto de prueba 1 TP-Shop",
"url": "https://admin.tilopay.com/link/3dNjE2MA3sdd==",
"callback_url": null,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/51087219_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 2,
"amount": "35.00",
"currency": "USD",
"reference": "Producto de prueba 2",
"url": "https://admin.tilopay.com/link/dwNjE2see3MA==",
"callback_url": null,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/64156766_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 3,
"amount": "45.00",
"currency": "USD",
"reference": "Producto de prueba 3",
"url": "https://admin.tilopay.com/link/f4NjE2MwsdA==",
"callback_url": null,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/88435879_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 4,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/ceNjE2sxw2MA==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 5,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/cweNjE2Mfd5A==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 6,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/ce3NjE2fg5eMA==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 7,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/dsNjE2MAd32==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 8,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/NjE2sd32MA==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 9,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/sd3NjE2MA==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
},
{
"id": 10,
"amount": "45.00",
"currency": "USD",
"reference": "test",
"url": "https://admin.tilopay.com/link/d3dNjE2MA==",
"callback_url": null,
"description": "ddd",
"times_used": null,
"picture": "https://storage.googleapis.com/tilo-uploads/items/37716065_.png",
"create": "2022-10-24 08:45:14"
}
]
}
}
```
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://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:
Id del link de pago a consultar.
Api Key del comercio.
## 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).
---
# Cobros Recurrentes
> Operaciones de cobros 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://tilopay.com/developers/api/recurrentes
## Operaciones [#operaciones]
16 operaciones en tres subgrupos:
- [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 · 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://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://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]
Key de la integración Tilopay.
Título del plan recurrente.
Descripción del plan.
Frecuencia de cobro.
| Código | Valor |
| --- | --- |
| 1 | Diario |
| 2 | Semanal |
| 3 | Mensual |
| 4 | Anual |
| 5 | Quincenal |
| 6 | Bimestral |
| 7 | Trimestral |
| 8 | Cuatrimestral |
| 9 | Semestral |
Código de moneda en formato ISO 4217.
Monto por pago inicial.
Activa el periodo de prueba gratis: 0 no, 1 sí.
Días del periodo de prueba gratis.
Cantidad de reintentos para cobros fallidos.
Array de modalidades del plan.
Campo opcional. URL de agradecimiento propia del comercio; debe soportar el método **GET**.
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'}`
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'}`
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}`
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'}`
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'}`
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.
En 1 agrega al correo de notificación el texto de `notify_detail` y `notify_note`. En 0 no agrega ninguno de los dos.
Texto del detalle en español. Opcional si `notify` es 0.
Texto del detalle en inglés. Opcional si `notify` es 0.
Texto de las notas en español. Opcional si `notify` es 0.
Texto de las notas en inglés. Opcional si `notify` es 0.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"key": "",
"title": "Plan title",
"description": "Plan description",
"frecuency": 1,
"currency": "USD",
"first_amount": 0,
"trial": 0,
"trial_days": 0,
"attempts": 1,
"modality": [
{
"title": "Basic",
"amount": 10
},
{
"title": "Premium",
"amount": 30
}
],
"thanks_url": "",
"webhook_subscribe": "",
"webhook_payment": "",
"webhook_rejected": "",
"webhook_unsubscribe": "",
"webhook_reactive": "",
"end_at": "25-10-2023",
"notify": 0,
"notify_detail_es": "",
"notify_detail_en": "",
"notify_note_es": "",
"notify_note_en": ""
}
```
## 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://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]
Key de la integración Tilopay.
Id del plan recurrente.
Título del plan recurrente.
Descripción del plan.
Frecuencia de cobro.
| Código | Valor |
| --- | --- |
| 1 | Diario |
| 2 | Semanal |
| 3 | Mensual |
| 4 | Anual |
| 5 | Quincenal |
| 6 | Bimestral |
| 7 | Trimestral |
| 8 | Cuatrimestral |
| 9 | Semestral |
Código de moneda en formato ISO 4217.
Monto por pago inicial.
Activa el periodo de prueba gratis: 0 no, 1 sí.
Días del periodo de prueba gratis.
Cantidad de reintentos para cobros fallidos.
Estado del plan recurrente.
| Código | Valor |
| --- | --- |
| 0 | Inactivo |
| 1 | Activo |
| 2 | Activo pero sin registros nuevos |
Campo opcional. URL de agradecimiento propia del comercio; debe soportar el método **GET**.
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'}`
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'}`
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}`
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'}`
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'}`
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.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"key": "",
"id": 3,
"title": "Plan title",
"description": "Plan description",
"frecuency": 2,
"currency": "USD",
"first_amount": 0,
"trial": 0,
"trial_days": 0,
"attempts": 5,
"status": 1,
"thanks_url": "",
"webhook_subscribe": "",
"webhook_payment": "",
"webhook_rejected": "",
"webhook_unsubscribe": "",
"webhook_reactive": "",
"end_at": "25-10-2023"
}
```
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://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]
Key de la integración Tilopay.
Id del plan recurrente.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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]
Key de la integración Tilopay.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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]
Key de la integración Tilopay.
Id del plan recurrente.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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://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]
Key de la integración Tilopay.
Id del plan recurrente.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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]
Key de la integración Tilopay.
Id del suscriptor.
Estado del suscriptor.
| Código | Valor |
| --- | --- |
| 1 | Activo |
| 3 | Pausado |
| 4 | Eliminado |
Fecha de expiración del plan, formato `yy-m-d`.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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]
Key de la integración Tilopay.
Id del suscriptor.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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]
Key de la integración Tilopay.
Id del suscriptor.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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]
Key de la integración Tilopay.
Id del suscriptor.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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]
Key de la integración Tilopay.
Id del plan recurrente.
Correo del usuario para el que se quiere crear el link de registro.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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]
Key de la integración Tilopay.
Id del plan recurrente.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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://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]
Key de la integración Tilopay.
Id del plan recurrente.
Permiso de usuarios.
| Código | Valor |
| --- | --- |
| 0 | Permitir solo usuarios nuevos |
| 1 | Permitir usuarios ya registrados |
Tipo de descuento.
| Código | Valor |
| --- | --- |
| 1 | Porcentaje |
| 2 | Monto fijo |
Valor numérico del descuento.
Fecha de expiración del cupón, formato `Y-m-d` (por ejemplo 2025-10-20).
Permiso de correos.
| Código | Valor |
| --- | --- |
| 1 | Correos específicos |
| 2 | Cualquier correo |
Lista de correos separados por coma. Requerido si `email_group` se envía en 1.
Cantidad total de usos.
Cantidad total de renovaciones válidas.
Total de usos por un mismo usuario.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"key": "",
"planId": 10,
"active_users": 1,
"type_discount": 1,
"discount": 40,
"expire": "2025-10-20",
"email_group": 1,
"email": "cliente@ejemplo.com, cliente@ejemplo.com",
"usage": 1,
"renews": 2,
"renews_by_user": 2
}
```
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://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]
Key de la integración Tilopay.
Id del plan recurrente.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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]
Key de la integración Tilopay.
Id del cupón.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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]
Key de la integración Tilopay.
Id del cupón.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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).
---
# Credential on File (CoF)
> Operaciones de credential on file (cof) del API de Tilopay, con parámetros y ejemplos.
- kind: api-index
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://tilopay.com/developers/api/cof
## Operaciones [#operaciones]
3 operaciones:
- [Tokenizar tarjeta](/developers/api/cof/process-tokenize) — 1
- [Eliminar tarjeta](/developers/api/cof/remove-card) — 1
- [Realizar cobro](/developers/api/cof/realizar-cobro) — 1
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 CoF (Tokenizar)
> 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://tilopay.com/developers/api/cof/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]
Sitio donde espera la respuesta de la transacción.
Key asociado al comercio.
Correo electrónico del tarjetahabiente.
Idioma [es, en].
Nombre del tarjetahabiente.
Apellido del tarjetahabiente.
Enviar como valor "v2".
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"redirect": "https://urlToRedirect.com",
"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 CoF
> 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://tilopay.com/developers/api/cof/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]
Llave relacionada con el comercio.
Correo del cliente asociado al token.
Token a eliminar.
## 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 · Realizar cobro CoF
> Cobro servidor a servidor con token de tarjeta v2 mediante Credential on File.
- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-08-29
- url: https://tilopay.com/developers/api/cof/realizar-cobro
```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]
Llave relacionada con el cliente. Se obtiene en Admin · Tilopay Checkout.
Monto de la compra.
Moneda de la compra en formato ISO, por ejemplo USD, CRC, GTQ.
Número de orden, puede ser alfanumérico.
Captura y autoriza: 1 sí, 0 no.
Correo del tarjetahabiente.
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.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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).
---
# 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://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://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]
Ejemplo: `1214352`
Ejemplo: `2`
Ejemplo: `1.00`
Llave relacionada con el cliente. Se obtiene en Admin · Tilopay Checkout.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"orderNumber": "1214352",
"type": "2",
"amount": "1.00",
"key": ""
}
```
## Respuesta [#respuesta-modificacion]
Tipo de modificación aplicada.
Identificador de la transacción.
Código de resultado de la modificación.
Texto del resultado.
Hash de la orden. Ver la nota sobre `orderHash` en [webhooks](/developers/api/webhooks#verificacion).
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://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]
Key de la integración Tilopay.
Número de orden consultado.
Id de comercio.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"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://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]
Key de la integración Tilopay.
Fecha de inicio, formato `Y-m-d H:i:s` — por ejemplo "2022-01-15 00:00:00".
Fecha de fin, formato `Y-m-d H:i:s` — por ejemplo "2022-08-01 23:59:59".
Indica si se obtienen solo transacciones aprobadas.
| Código | Valor |
| --- | --- |
| 0 | Cualquiera |
| 1 | Solo aprobadas |
Ambiente de las transacciones a obtener.
| Código | Valor |
| --- | --- |
| 0 | Producción |
| 1 | Pruebas |
Array de monedas que se desean obtener, por ejemplo ["USD", "CRC"].
Id de comercio.
Número de orden.
Correo del cliente.
Número de autorización.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"key": "",
"startDate": "2023-06-01 00:00:00",
"endDate": "2023-06-30 23:59:59",
"onlyAproved": 1,
"environment": 1,
"currency": [
"USD",
"CRC"
],
"merchantId": "",
"orderNumber": "12135",
"email": "customer@example.com",
"auth": "123456"
}
```
## 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": "",
"code": "1",
"response": "Transacción aprobada",
"auth": "123456",
"card": "4021",
"last": "5221",
"email": "customer@example.com",
"commission": 0.18,
"iva_commission": 0.02,
"retention_iva": 0.27,
"retention_rent": 0.09,
"cost": 0.35,
"cost_iva": 0.05,
"net_to_liquidate": 4.04,
"capture": "Capture",
"type": "Payment",
"environment": "Production",
"date": "2024-07-31 16:59:20"
},
{
"id": 734330,
"orderNumber": "12136",
"amount": "5.00",
"taxes": "0.00",
"discount": "0.00",
"discount_name": "",
"currency": "USD",
"merchantId": "",
"code": "1",
"response": "Transacción aprobada",
"auth": "123456",
"card": "4021",
"last": "5221",
"email": "customer@example.com",
"commission": 0.18,
"iva_commission": 0.02,
"retention_iva": 0.27,
"retention_rent": 0.09,
"cost": 0.35,
"cost_iva": 0.05,
"net_to_liquidate": 4.04,
"capture": "Capture",
"type": "Payment",
"environment": "Production",
"date": "2024-07-31 17:25:35"
}
]
}
```
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://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]
Id de la orden aprobada en Tilopay.
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.
Idioma de la solicitud.
## 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": "",
"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).
---
# 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://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]
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 `soporte@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.
## Webhook del flujo principal [#processpayment]
`processPayment` también tiene webhook. Su especificación técnica (los campos que envía) **te la entregamos cuando la solicitás**, para que tu equipo lo implemente:
escribí a `soporte@tilopay.com` para recibirlo.
---
# 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://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/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.
---
# 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://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]
Usuario de API del comercio.
Contraseña de API del comercio.
Api key del comercio.
## Ejemplo de request [#request]
Los valores `<...>` son marcadores: reemplazalos por tus credenciales y datos.
```json
{
"apiuser": "",
"password": "",
"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).
---
# 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://tilopay.com/developers/sdk/instalacion
## El script [#script]
```html
```
Cargalo antes de tu propio código de checkout. El SDK expone el objeto global `Tilopay`.
## jQuery no es requerido [#jquery]
**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.
## Versiones [#versiones]
Existen solo dos versiones:
| Versión | Estado |
|---|---|
| `v1` | Sin soporte |
| `v2` | Actual |
## Lo que no hay [#garantias]
**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.
## 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://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.
**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.
## Campos [#campos]
Contiene el id del método de pago obtenido de Tilopay. Puede estar visible u oculto, a
tu discreción.
Contiene el id de la tarjeta guardada obtenida de Tilopay. Si el cliente no tiene tarjetas
guardadas, ocultalo.
Número de tarjeta.
Fecha de expiración en formato mes/año, por ejemplo `01/25`.
Código de seguridad. Cuando el cliente usa una tarjeta guardada, hay que habilitar este
campo para que digite el CVV.
Contenedor requerido, **fuera del formulario**. Es donde el SDK monta el flujo 3DS.
## 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
```
---
# 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://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 vos.
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]
Token del SDK, obtenido con `POST /api/v1/loginSdk`. Ver
[autenticación](/developers/api/autenticacion).
Moneda de la compra, ISO 4217.
**Idioma** del checkout, ISO 639-1. Solo se soportan `es` y `en`; por defecto carga `es`.
Monto de la compra.
Correo del cliente. Es obligatorio para que la respuesta traiga las tarjetas guardadas.
Número de orden, único por comercio. Ver
[reintentos seguros](/developers/reintentos-seguros).
Tipo de identificación del cliente. Condicionado. Ver la
[tabla de tipos](/developers/sdk/reference/update-options#tipos-de-identificacion).
Número de identificación del cliente. Condicionado.
Nombre del cliente.
Apellidos del cliente.
Dirección 1 del cliente.
Dirección 2 del cliente. Opcional.
Ciudad. Recomendado.
Provincia o estado. Recomendado.
Código postal. Recomendado.
País, ISO 3166-1 alpha-2. Recomendado.
Teléfono del cliente. Recomendado.
`0` autoriza; `1` autoriza y captura.
URL donde el SDK renderiza la respuesta final de la compra.
`1` guarda la tarjeta del cliente en Tilopay; `0` no la guarda.
Teléfono Yappy. Obligatorio cuando se paga con Yappy. No se toma del DOM.
Opcional. Valores `"V1"` o `"V2"`. Si no se envía, el hash de la respuesta final se fabrica
con V1.
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.
## 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]
`Success`, o la descripción del error.
`0` producción, `1` pruebas. Ver [entornos](/developers/entornos).
Objeto con `code` y `amount`, presente cuando tenés SINPE Móvil. Los datos
completos, incluido el teléfono destino, se obtienen con
[`getSinpeMovil()`](/developers/sdk/reference/get-sinpe-movil).
Arreglo de `{id, name, type}` con los métodos de pago disponibles.
Arreglo de `{id, name, brand}` con las tarjetas guardadas del cliente.
## 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).
---
# 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://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
```
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://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"
}
```
La marca de la tarjeta.
## 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://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 tenés un método SINPE Móvil disponible y el cliente lo selecciona de la
lista que devolvió [`Init()`](/developers/sdk/reference/init).
**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.
## 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"
}
```
`Success` cuando la operación salió bien.
El código que el cliente debe escribir en la descripción de la transferencia. Es lo que permite
identificar el pago.
El monto exacto que debe transferir.
El número de teléfono destino de la transferencia.
### 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://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.
**Es un patch.** Se envían solo los campos que se quieren actualizar; no hay que reenviar todo.
## 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]
Tipo de identificación del cliente. Obligatorio para SINPE Móvil. Ver
[tipos de identificación](#tipos-de-identificacion).
Número de identificación del cliente. Obligatorio para SINPE Móvil. **Acepta con guiones y sin
guiones.**
Nombre del cliente.
Apellidos del cliente.
Dirección 1 del cliente.
Dirección 2 del cliente. Opcional.
Ciudad del cliente. Recomendado.
Provincia o estado. Recomendado.
Código postal. Recomendado.
País, ISO 3166-1 alpha-2. Recomendado.
Teléfono del cliente. Recomendado.
`0` autoriza; `1` autoriza y captura.
URL donde se espera la respuesta final de la compra.
`1` si el cliente quiere guardar su tarjeta en Tilopay; `0` si no.
Teléfono Yappy. Obligatorio cuando el cliente paga con Yappy.
**`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.
## 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"
}
```
`Success` cuando la actualización salió bien; la descripción del error en caso contrario.
---
# API Bancario de Tilopay
> Referencia del API Bancario (BaaS) de Tilopay generada desde su spec OpenAPI 3.0.3, versión 1.0.0.
- kind: api-index
- status: stable
- api_version: 1.0.0
- last_verified: 2026-10-09
- url: https://tilopay.com/developers/api-bancario
Con nuestro API Bancario podés iniciar pagos (PIN y SINPE Móvil), consultar su estado,
administrar tus cuentas y recibir webhooks de eventos de pago desde tus propios sistemas,
siempre limitado a las cuentas que autoriza tu token de acceso.
**Es un producto separado de la pasarela de pagos.** Corre en su propia infraestructura,
con host, credenciales y autenticación propias. Si ya integrás nuestro API de
adquirencia, el acceso a este se habilita por separado.
En esta documentación encontrás los endpoints, modelos y flujos oficiales de la versión
**1.0.0** del API Bancario.
## Qué permite hacer [#que-permite]
**Pagos.** Creá un pago, consultalo por identificador, listalo por cuenta y buscalo por
`payment_id`, `public_id` o `client_reference`; los métodos disponibles son `PIN` y
`SINPE_MOVIL`, en dirección `OUT` o `IN`.
[Ver operaciones de pagos](/developers/api-bancario/pagos).
**Cuentas.** Validá una cuenta destino antes de transferir, listá tus cuentas con o sin
saldos, consultá el saldo de una cuenta y solicitá estados de cuenta de forma asincrónica.
[Ver operaciones de cuentas](/developers/api-bancario/cuentas).
**Webhooks.** Registrá tu destino HTTPS cifrado, consultá los eventos a los que podés
suscribirte por método de pago y la estructura de datos que te enviamos en cada uno.
[Ver operaciones de webhooks](/developers/api-bancario/webhooks).
**Catálogos.** Tipos de persona de identificación de cliente por país.
[Ver catálogos](/developers/api-bancario/catalogos).
Además, ponemos a tu disposición `GET /api/public/v1/healthz` para chequeo de salud, y `GET
/openapi.yaml` y `GET /docs` con la definición OpenAPI y la documentación interactiva
directamente en el host del API.
## Entornos [#entornos]
Hay dos entornos, con las mismas rutas y contratos. El de pruebas:
```text
https://api-baas-sandbox.tilopay.com
```
El de producción es el mismo host sin el sufijo `-sandbox`:
```text
https://api-baas.tilopay.com
```
Podés empezar en el entorno de pruebas y, cuando estés listo, te entregamos las
credenciales de producción al habilitar tu acceso.
## Artefactos legibles por máquina [#artefactos]
Publicamos la definición OpenAPI completa del API Bancario, con CORS abierto, en dos formatos:
- [openapi.json](/developers/api-bancario/openapi.json)
- [openapi.yaml](/developers/api-bancario/openapi.yaml)
Es independiente de la definición de nuestro API de adquirencia
([/developers/openapi.json](/developers/openapi.json)): son dos productos separados.
## Cómo obtener acceso [#acceso]
El acceso es restringido y se otorga por solicitud, para operaciones en Costa Rica.
Para conocer el producto y solicitarlo, visitá [baas.tilopay.com](https://baas.tilopay.com),
indicando volumen mensual estimado, caso de uso y sistemas a integrar.
## Por dónde seguir [#siguiente]
1. [Autenticación](/developers/api-bancario/autenticacion) — login, intercambio de token y Bearer.
2. [Convenciones](/developers/api-bancario/convenciones) — envelope, correlación, reintentos seguros, paginación y fechas.
3. [Códigos de respuesta](/developers/api-bancario/errores) — catálogo completo de `response_code`.
---
# Autenticación del API Bancario
> Login, intercambio de token y uso del Bearer JWT en el API Bancario de Tilopay.
- kind: concept
- status: stable
- api_version: 1.0.0
- last_verified: 2026-09-02
- url: https://tilopay.com/developers/api-bancario/autenticacion
El API Bancario usa un flujo de dos pasos: primero autenticás al cliente con correo y
contraseña, después intercambiás el token resultante por un access token JWT que firma
todas las demás llamadas.
Los tres endpoints del grupo `Auth` son los únicos que **no** llevan `Authorization`.
Todo el resto del API exige `Authorization: Bearer `.
## Paso 1 — Login [#login]
```http
POST /api/public/v1/auth/login
```
Cuerpo requerido: `email` (formato email) y `password`.
```json
{
"email": "operaciones@comercio.com",
"password": "••••••••"
}
```
La respuesta `200` devuelve en `data`:
| Campo | Tipo | Descripción |
|---|---|---|
| `gidp_id_token` | string | Token de identidad para el paso 2. |
| `assignments` | array | Contextos disponibles del cliente. |
Cada elemento de `assignments` trae `assignment_id`, `owner_type`, `owner_id`,
`tenant_id`, `tenant_code`, `country_code`, `role`, `roles` y `status`. Elegí el
`assignment_id` del contexto con el que vas a operar.
## Paso 2 — Intercambio de token [#exchange]
```http
POST /api/public/v1/auth/token/exchange
```
Cuerpo requerido: `gidp_id_token` (el del paso 1) y `assignment_id` (el contexto
elegido).
```json
{
"gidp_id_token": "eyJhbGciOi...",
"assignment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```
La respuesta `200` devuelve en `data`:
| Campo | Tipo | Descripción |
|---|---|---|
| `token` | string | Access token JWT. |
| `expires_in` | integer | Vigencia del token en segundos. |
| `claims` | object | Contexto resuelto del token. |
`claims` incluye `sub`, `subject_kind`, `user_type`, `tenant_id`, `owner_type`,
`owner_id`, `roles`, `scopes`, `country_code`, `locale`, `channel`, `idp`, `idp_sub` e
`idempotency_key`.
## Paso 3 — Usar el Bearer [#bearer]
El esquema de seguridad declarado es `BearerAuth`: HTTP bearer con formato JWT.
```http
Authorization: Bearer
```
El contexto viaja **dentro** del token: no se envían `tenant_id`, `owner_id` ni
`owner_type` como parámetros en las operaciones de negocio. El token acota por sí solo a
qué cuentas y pagos podés acceder.
Cuando el token está ausente, vencido o es inválido, la respuesta es `401` con
`response_code: UNAUTHORIZED`. Si el token es válido pero el contexto no autoriza el
recurso, es `403` con `FORBIDDEN`. Repetí el paso 2 para renovar el access token antes de
que se cumpla `expires_in`.
## Contraseñas [#password]
```http
POST /api/public/v1/auth/request-set-password
```
Inicia el proceso de establecer o restablecer la contraseña del correo indicado. No
requiere autenticación previa y responde siempre igual, exista o no la cuenta, para no
revelar si un correo está registrado.
```json
{
"email": "operaciones@comercio.com"
}
```
---
# Convenciones del API Bancario
> Envelope de respuesta, correlación, reintentos seguros, paginación y formato de fechas del API Bancario.
- kind: concept
- status: stable
- api_version: 1.0.0
- last_verified: 2026-09-02
- url: https://tilopay.com/developers/api-bancario/convenciones
Todas las operaciones del API Bancario comparten el mismo formato de respuesta, las
mismas reglas de paginación y el mismo formato de fechas. Acá te explicamos esas reglas
comunes.
## Envelope de respuesta [#envelope]
Cada respuesta, exitosa o no, viaja en el mismo sobre:
```json
{
"success": true,
"http_status_code": 200,
"response_code": "OK",
"message": "The request was processed successfully.",
"correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"data": {}
}
```
| Campo | Tipo | Descripción |
|---|---|---|
| `success` | boolean | `true` en las respuestas exitosas; `false` en las de error. |
| `http_status_code` | integer | Repite el status HTTP en el cuerpo. |
| `response_code` | string | Código del [catálogo de `response_code`](/developers/api-bancario/errores). |
| `message` | string | Mensaje legible de la respuesta. |
| `correlation_id` | string | Identificador de la llamada. |
| `data` | object | Carga útil de la operación. |
En las respuestas de error el sobre trae además `errors`, un objeto de detalle que puede
incluir campos arbitrarios como `code`, `message` o `detail`.
Ramificá tu lógica por `response_code`, no por el texto de `message`.
## Correlación [#correlacion]
Enviá `X-Correlation-Id` en el request para propagar tu propio identificador; el valor
vuelve como `correlation_id` en el sobre. Guardalo en tus logs: es el dato con el que
soporte rastrea una llamada puntual.
## Reintentos seguros [#reintentos]
Dos operaciones aceptan la cabecera `Idempotency-Key`:
```http
POST /api/public/v1/transactions/payments
POST /api/public/v1/accounts/statements
```
Reenviar la misma llave con el mismo cuerpo devuelve el resultado original en vez de
crear un segundo registro, así un timeout de red se puede reintentar sin duplicar. Si
reusás una llave con un cuerpo distinto, la respuesta es `409` con
`response_code: IDEMPOTENCY_CONFLICT`.
Generá una llave por intención de negocio (por ejemplo un UUID por orden), no una por
reintento. El resto de las operaciones son consultas y se pueden repetir sin efectos
adicionales.
## Paginación [#paginacion]
El API usa dos esquemas según el recurso.
**Cursor, en el listado de pagos.** `GET /api/public/v1/transactions/payments` acepta
`limit` (por defecto 20, máximo 100) y `cursor`. La respuesta trae
`pagination.next_cursor`: pasalo como `cursor` en el siguiente request. Cuando viene
vacío u omitido, no hay más páginas.
**Offset, en cuentas.** `GET /api/public/v1/accounts` y
`GET /api/public/v1/accounts/balances` aceptan `limit` (1 a 100) y `offset` (desde 0), y
devuelven `pagination` con `limit`, `offset` y `total`.
## Fechas y montos [#formatos]
Los parámetros y campos de fecha usan RFC 3339, por ejemplo
`2026-09-02T15:04:05Z`. Los filtros `date_from` y `date_to` del listado de pagos siguen
ese mismo formato.
## Salud y documentación del host [#host]
El propio host expone tres rutas de servicio:
```http
GET /api/public/v1/healthz
GET /openapi.yaml
GET /docs
```
`healthz` sirve para chequeo de disponibilidad, `openapi.yaml` devuelve la definición OpenAPI y
`/docs` la documentación interactiva. En este portal también la publicamos en
[openapi.json](/developers/api-bancario/openapi.json) y
[openapi.yaml](/developers/api-bancario/openapi.yaml).
---
# Pagos del API Bancario
> Operaciones de pagos del API Bancario: crear, consultar, listar y buscar pagos PIN y SINPE Móvil.
- kind: api-operation
- status: stable
- api_version: 1.0.0
- last_verified: 2026-09-02
- url: https://tilopay.com/developers/api-bancario/pagos
El grupo `Payments` cubre el ciclo completo de un pago: crearlo, consultarlo por
identificador, listarlo con filtros y buscarlo por cualquiera de sus referencias.
```http
POST /api/public/v1/transactions/payments
GET /api/public/v1/transactions/payments
GET /api/public/v1/transactions/payments/{payment_id}
POST /api/public/v1/transactions/payments/search
```
## Reglas del recurso [#reglas]
**Métodos.** `payment_method_code` admite `PIN` y `SINPE_MOVIL`. **Dirección.**
`direction` admite `OUT` (salida) e `IN` (entrada). **Cuenta destino.** se identifica por
`IBAN` o por `PHONE`, según el método.
**Referencia propia.** `client_reference` es tu identificador del pago y es único por
tenant: dos pagos del mismo cliente no pueden compartirlo. Sirve para buscar el pago sin
guardar el `payment_id`.
**Reintentos seguros.** La creación acepta `Idempotency-Key`; reenviar la misma llave con
el mismo cuerpo devuelve el pago original en vez de crear otro. Ver
[reintentos seguros](/developers/api-bancario/convenciones#reintentos).
## Estados [#estados]
Un pago recorre cinco estados: `pending`, `processing`, `confirmed`, `posted` y `failed`.
La reversión **no es un estado**: un pago revertido sigue en `posted` y se reconoce por
`result: reversed` y `has_reversal: true`, además del evento
[`payment.reversed`](/developers/api-bancario/webhooks). Consultá siempre esos dos campos
antes de dar un pago por definitivo.
## Operaciones [#operaciones]
### List customer payments [#get-transactions-payments]
```http
GET /api/public/v1/transactions/payments
```
Host: `https://api-baas-sandbox.tilopay.com` — requiere `Authorization: Bearer `.
Simple REST list of payments for an owned account (IBAN).
Filters are query parameters. Ownership (`tenant_id`, `owner_type`, `owner_id`)
is derived from the access token; clients must not send ownership filters.
**Account identification (required):** `type` + `value` (identifier
scheme + value, e.g. `IBAN` + IBAN string). This is not the internal
account classification.
Pagination is cursor-based (`limit`, `cursor`). Default limit is 20 (max 100).
`status` in the response and as a filter uses the public lowercase catalog
(`pending`, `processing`, `confirmed`, `posted`, `failed`). Same values as webhooks.
REST also returns `status_detail` (uppercase operational name).
Each item includes a consolidated `result` (`succeeded`, `failed`, `reversed`, `pending`)
for reconciliation when a webhook was missed. `status` is only the processing/lifecycle
catalog and does not change to `failed` when a posted payment is later reversed —
use `result=reversed` and `has_reversal=true` (webhook `payment.reversed`).
`error` is `null` when there is no failure information; it is an object only when
`domain` / `platform` is present (`result` is `failed` or `reversed`), same shape
as webhook `payment.failed` `payment.error`.
`source` / `destination` use `null` for unknown `account`, `name`, and `identification`;
account values are IBAN or PHONE only (never ledger UUIDs).
For PIN payments created after public identification persistence,
`identification.number` is the partner-submitted public number (no SINPE hyphens);
older payments may still show the hyphenated SINPE form. See `docs/PAYMENT-IDENTIFICATION.md`.
**Parámetros**
| Parámetro | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `X-Correlation-Id` | header | string | — | Optional client-supplied correlation id for end-to-end tracing. Echoed back as `correlation_id` in the response envelope. If omitted, the API generates one and still returns it. |
| `type` | query | string | sí | Account **identifier scheme** (e.g. `IBAN`). This is **not** the internal account classification (e.g. operational). Values: IBAN |
| `value` | query | string | sí | Account identifier value (IBAN). Spaces are ignored. |
| `status` | query | string | — | Optional payment status filter. Public catalog is lowercase: `pending`, `processing`, `confirmed`, `posted`, `failed`. Uppercase aliases of the same values are accepted. Legacy values such as `INITIATED` map to `pending`. Values: pending, processing, confirmed, posted, failed |
| `date_from` | query | string (date-time) | — | Inclusive lower bound for `created_at`. RFC 3339 (UTC `Z` or offset; optional fractional seconds). |
| `date_to` | query | string (date-time) | — | Inclusive upper bound for `created_at`. RFC 3339 (UTC `Z` or offset; optional fractional seconds). |
| `client_reference` | query | string | — | Filter by partner client reference (exact match against the value sent at payment creation). |
| `currency` | query | string | — | Filter by payment currency (ISO 4217, e.g. CRC). |
| `payment_method_code` | query | string | — | Filter by public payment method code. Values: PIN, SINPE_MOVIL |
| `direction` | query | string | — | Filter by payment direction. Accepts public values `OUT`/`IN` or `PAYOUT`/`PAYIN` (internally normalized to `payout`/`payin`). Values: OUT, IN, PAYOUT, PAYIN |
| `limit` | query | integer | — | Page size (default 20, max 100). |
| `cursor` | query | string | — | Opaque cursor from a previous response `pagination.next_cursor`. |
**200** — The request was processed successfully.
`response_code`: `OK`
Campos de `data`:
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `items` | array