Saltar al contenido
TilínDocumentación de la API tilinapp.online

API de Tilín

Para conectar otro programa —un sistema de facturación, una tienda, el software que le rentas a tus clientes— y que los pagos se confirmen solos.

Todos los ejemplos de este documento son respuestas reales capturadas del servidor, no inventadas. Cámbiale el dominio y funcionan tal cual.

1. Autenticación

Hay dos clases de token y los dos se usan igual; lo que cambia es hasta dónde llegan. (Hay una tercera llave, la de socio tp_…, que no es de ninguna cuenta: sirve solo para dar de alta cuentas desde otro programa. Está en la sección 9.)

El token de la cuenta

Se saca en Panel ▸ Mi cuenta ▸ Generar token nuevo y se enseña una sola vez: en la base solo queda su huella, así que si se pierde hay que generar otro (el anterior deja de valer en ese momento). Hay uno por cuenta.

Va en cada llamada:

Authorization: Bearer vb_a1b2c3…

Sin token, o con uno inventado, todo responde 401.

Ese token es la cuenta entera. Guárdalo en el servidor, nunca en el navegador ni en una app que instale el cliente: con él se pueden crear cobros, ver el historial y leer los movimientos. Si sospechas que se filtró, genera uno nuevo desde el panel y el viejo muere.

Tokens por programa, atados a una cuenta Nequi

Si conectas más de un programa, o si el negocio tiene varias cuentas Nequi (un local por cada una), ese token no sirve bien: es uno solo, lo abre todo, y cambiarlo tumba a la vez a todo lo que lo estuviera usando.

En Panel ▸ Mi cuenta ▸ Tokens por programa se saca uno para cada integración, y a cada uno se le puede poner una dirección. Un token con dirección:

Si pregunta por un cobro de otra dirección, la respuesta es 404 —la misma que para un id que no existe: así no se puede averiguar qué hay al otro lado—. Y si entra por una parte de la API que no sabe filtrar por dirección, 403:

{ "error": "Ese token está limitado a una dirección y no puede usar esta parte de la API." }

Esa lista es cerrada por omisión: lo que se le añada a la API más adelante nace prohibido para estos tokens hasta que se le enseñe a respetar el alcance. Vale para cobrar (/api/charges), leer movimientos (/api/transactions), validar (/api/validate), el QR suelto (/api/qr) y la lista de direcciones (/api/mailboxes).

2. Convenciones

FormatoJSON en ambos sentidos. En los POST, manda Content-Type: application/json
MontosNúmeros en pesos colombianos. 120000 son ciento veinte mil
FechasISO 8601 con zona: 2026-10-07T18:41:08-05:00
Zona horariaPor omisión la del servidor. Mándala con la cabecera X-Timezone: America/Bogota y las fechas te llegan en esa
ErroresSiempre {"error": "explicación en español"}, pensada para poder enseñársela a una persona

Códigos que vas a ver:

 tu software                     Tilín                      tu cliente
     │                             │                             │
     │ 1. POST /api/charges ──────▶│                             │
     │◀──── id, url, amount        │                             │
     │                             │                             │
     │ 2. le mandas el url ────────┼────────────────────────────▶│
     │                             │       3. abre y paga ◀──────│
     │                             │◀── llega el correo del banco│
     │ 4. GET /api/charges/{id} ──▶│                             │
     │◀──── status: "pagado"       │                             │

Paso 1 — crear el cobro

curl -X POST https://tilinapp.online/api/charges \
  -H "Authorization: Bearer vb_tu_token" \
  -H "Content-Type: application/json" \
  -d '{"amount": 120000, "reference": "SUSCRIPCION-OCT", "concept": "Plan mensual", "minutes": 1440}'
{
  "id": 1,
  "token": "47anrc847vjx6um98crmjm",
  "url": "https://tilinapp.online/c/47anrc847vjx6um98crmjm",
  "amount": 120000,
  "reference": "SUSCRIPCION-OCT",
  "concept": "Plan mensual",
  "status": "pendiente",
  "payload": "00020101021226320014CO.COM.RBM.LLA0410@minegocio…6304EA5A",
  "key": "@minegocio",
  "anyBank": false,
  "requested": 120000,
  "bump": 0,
  "createdAt": "2026-10-07T18:41:08-05:00",
  "expiresAt": "2026-10-08T18:41:08-05:00",
  "paidAt": null,
  "payer": null,
  "payReference": null,
  "payBank": null
}

Guarda el id junto a tu factura. Al cliente mándale el url.

Paso 4 — preguntar si ya pagaron

curl https://tilinapp.online/api/charges/1 -H "Authorization: Bearer vb_tu_token"
{
  "id": 1,
  "status": "pagado",
  "amount": 120000,
  "reference": "SUSCRIPCION-OCT",
  "paidAt": "2026-10-07T18:41:08-05:00",
  "payer": "CLIENTE UNO",
  "payReference": "M77001122",
  "payBank": "Nequi"
}

Cuando status es pagado, el pago entró de verdad: lo confirmó el correo del banco, no el cliente. Ahí tu software ya puede renovar la suscripción.

4. Cuatro cosas que hay que entender antes de programar

El monto puede no ser el que pediste

Si tu cuenta ya tenía otro cobro pendiente por esa misma cifra, al nuevo se le suman uno o dos pesos. La respuesta lo dice: requested es lo que pediste, bump lo que se sumó, amount lo que hay que pagar.

No es un capricho. El correo que manda el banco no trae la referencia que va dentro del QR —está comprobado con pagos reales de Nequi—, así que lo único que llega es el monto, el nombre de quien pagó y una referencia que inventa el banco. Con dos cobros de $120.000 esperando, un pago de $120.000 no se puede atribuir a ninguno de los dos. Con un peso de diferencia, sí.

Usa siempre el amount de la respuesta para mostrárselo al cliente. Si le enseñas el que pediste, pagará la cifra equivocada y el cobro se quedará esperando.

Los cobros caducan

Por omisión a los 20 minutos (se cambia en Panel ▸ Mi cuenta ▸ Cobros con QR, o por cobro con minutes). Un cobro vencido pasa a status: "vencido" y deja de aceptar pagos.

Para una suscripción mensual que mandas por correo, pon algo largo: "minutes": 1440 es un día. Para un cobro de mostrador, déjalo corto.

Una cuenta puede tener varias cuentas Nequi

Cada dirección de correo que el negocio tenga conectada puede llevar su propia llave Bre-B: su propia cuenta Nequi. Un cobro se crea contra una dirección (mailboxId) y eso decide dos cosas: con qué llave sale el QR —a qué cuenta le entra la plata— y qué pago puede cerrarlo. Un pago que entra en el local del norte no cierra un cobro del local del sur, ni aunque el monto cuadre.

Si no mandas mailboxId, el cobro queda sin dirección: sale con la llave de la cuenta y lo puede cerrar un pago que entre por cualquiera de ellas. Con una sola cuenta Nequi eso es lo normal y no hay nada que hacer.

Cada cobro te dice a qué dirección pertenece, que es cómo sabes qué cuenta cobró:

{ "mailboxId": 2, "mailbox": "Local norte" }

Un pago cierra un solo cobro

Un mismo pago no puede cerrar dos cobros, y el pago de una cuenta no cierra el cobro de otra. Además el pago tiene que haber ocurrido mientras el link estaba vivo: uno de ayer no cierra un cobro creado hoy.

5. Referencia

Cobros

MétodoRutaQué hace
POST/api/chargesCrea un cobro. Devuelve 201
GET/api/charges/{id}Un cobro y su estado
GET/api/chargesEl historial
POST/api/charges/{id}/cancelAnula uno pendiente

POST /api/charges — campos del cuerpo:

CampoObligatorioQué es
amountsíEl monto. Mayor que cero
referencenoTu referencia, hasta 25 caracteres (SUSCRIPCION-OCT). Sale en el panel y en el comprobante
conceptnoPara qué es, hasta 190 caracteres. Se le enseña al cliente
minutesnoCuánto vive el link. Por omisión, lo configurado en la cuenta
mailboxIdnoA qué cuenta Nequi se le cobra. Los ids salen de GET /api/mailboxes. Con un token limitado se ignora: cobra siempre a la suya
webhookUrlnoA dónde avisarte cuando este cobro quede pagado (o venza). https://. Hace falta el secreto de la cuenta — ver abajo
feePayernoQuién paga la comisión de ESTE cobro: comercio o cliente. Sin mandarlo, lo que tenga puesto la cuenta

GET /api/charges — parámetros opcionales: status (pendiente, pagado, vencido, anulado), limit (hasta 200) y mailbox (el id de una dirección, para ver solo los de un local). Devuelve {"charges": [...]} con lo último primero.

Campos de un cobro:

CampoQué es
idEl que guardas tú para preguntar después
token, urlEl link que se le manda al cliente
amountLo que hay que pagar (puede traer el ajuste)
reference, conceptLo que mandaste al crearlo, tal cual. null si no mandaste nada
requested, bumpLo pedido y lo sumado. Solo al crearlo
statuspendiente · pagado · vencido · anulado
mailboxId, mailboxA qué dirección se le cobró: el id y su nombre. null si el cobro es de la cuenta y no de un local
payloadEl contenido del QR, por si lo dibujas tú. Ya lleva el valor dentro
keyLa llave Bre-B que lleva dentro ese código, para ofrecer una transferencia
anyBanktrue si el código lo lee la app de cualquier banco; false si solo Nequi. Ver abajo
feeLo que te costó de comisión del servicio. null mientras no esté pagado, y null siempre si no tienes tarifa
feePayercomercio o cliente. No confundir con payer, que es quién pagó
baseAmountLo que vas a recibir tú, si la comisión va encima. null si la pagas tú
surchargeLo que se le sumó al precio. null si la pagas tú
webhookUrlA dónde se avisará de este cobro, si lo pediste al crearlo. null si no
createdAt, expiresAt, paidAtFechas con zona
payerQuién pagó, tal como lo manda el banco
payReference, payBankComprobante del banco y de qué banco vino

Un solo código, y de dónde sale

Hay un payload por cobro y siempre lleva el valor dentro: quien paga escanea y confirma, sin teclear nada. Lo que cambia es quién lo puede leer, y eso lo dice anyBank:

{
  "payload": "00020101…",
  "key": "@midavivienda",
  "anyBank": true
}

Ojo con key: es la llave que lleva dentro ese código, no la que el negocio tenga puesta en su cuenta. Cuando el cobro sale del QR del banco, las dos pueden ser distintas, y la que vale es esta — si alguien transfiere a otra, el dinero entra a otra cuenta y el cobro se queda esperando.

anyBankDe dónde saleQuién lo lee
trueDel QR de comercio del banco del negocio, con el importe insertadoLa app de cualquier banco
falseArmado con la llave del negocioSolo Nequi. Los demás responden «código no habilitado»

Sale true cuando el negocio pegó su QR del banco en el panel, y es lo que hay que querer. Con false, a quien no use Nequi se le ofrece la transferencia Bre-B a key.

Lo que hay que enseñar: el payload, y debajo key con un botón de copiar. La llave es el camino que funciona desde cualquier banco pase lo que pase, así que va visible y no escondida. Es lo que hace la página de /c/{token}, por si prefieres mandar ese link y no montar pantalla.

Esto llegó a documentarse al revés —dos códigos, y que al del banco no se le podía insertar el importe porque rompía la firma de la red—. No lo rompe: la firma del campo 91 no cubre la etiqueta del monto, y está comprobado pagando desde dos bancos distintos. Lo que fallaba era una app de Android desactualizada.

Anular devuelve el cobro ya anulado, o 422 si no estaba pendiente:

{ "error": "Solo se puede anular un cobro que siga pendiente." }

Tu saldo con el servicio

Hay un solo saldo y dos cosas que lo consumen:

Pagar es recargar el saldo: no hay una segunda forma de pagar ni un cobro aparte de la suscripción. Y si el saldo se pasa del límite, además de cortarse los cobros con link deja de sonar el aviso en el teléfono.

MétodoRutaQué hace
GET/api/feesTu saldo, tu tarifa y tu extracto
POST/api/fees/topupPrepara una recarga y te devuelve el QR para pagarla

GET /api/fees — si a tu cuenta no se le cobra nada, responde {"active": false} y ya:

{
  "active": true,
  "balance": -2900,
  "debt": 2900,
  "limit": 30000,
  "blocked": false,
  "fixed": 500,
  "percent": 2,
  "monthly": 30000,
  "monthlyDay": 12,
  "suggested": 3000,
  "ledger": [
    { "kind": "comision", "amount": -2900, "at": "2026-10-14T09:12:04-05:00", "chargeAmount": 120000 }
  ]
}
CampoQué es
balanceTu saldo. Positivo es saldo a favor; negativo es lo que debes
debtLo que debes, en positivo, para no tener que darle la vuelta al signo
limitHasta cuánto se te fía. null = no se te corta nunca; 0 = prepago puro
blocked, blockedReasonSi tienes los cobros con link cortados, y el motivo en palabras
fixed, percentTu tarifa por cobro con link, para que puedas rehacer la cuenta de cualquier transacción
monthly, monthlyDayLa cuota del servicio y el día del mes en que se te carga. 0 y null si no tienes cuota
suggestedLo que te proponemos recargar: lo que debes, redondeado hacia arriba
ledgerLos últimos movimientos: comision, recarga o ajuste

POST /api/fees/topup con {"amount": 20000} (o sin cuerpo, y usa suggested) devuelve el cobro con el que pagas:

{
  "amount": 20000,
  "url": "https://tilinapp.online/c/9x2mq…",
  "payload": "00020101…",
  "anyBank": true,
  "expiresAt": "2026-10-15T09:12:04-05:00"
}

Dibuja el payload o manda el url. No hay que confirmar nada: cuando el pago entra, el saldo sube solo, igual que se cierran tus propios cobros con link. Mientras esperas puedes ir preguntando por GET /api/fees y mirar balance.

Pedir dos recargas seguidas por el mismo importe devuelve la misma, no dos. Y si estás cortado, esto sigue funcionando: cortarte el camino para pagar sería absurdo.

Si administras el servicio: la recarga de otra cuenta

Esto es solo para el operador y pide un token de una cuenta administradora.

MétodoRutaQué hace
POST/api/admin/users/{id}/fees/topupPrepara la recarga de ESE cliente

Mismo cuerpo ({"amount": 30000}, o vacío para lo que deba) y misma respuesta que /api/fees/topup. Sirve para generarle el link desde tu propia herramienta y mandárselo, sin pedirle que entre al panel — que es justo lo que menos apetece hacer cuando te acaban de cortar la cuenta.

El cobro sale contra la llave del cobrador, no la del cliente: el dinero entra a quien presta el servicio. Y responde 404 si ese id no existe, 403 si el token no es de administrador.

Que te avisen cuando te paguen

Preguntar por GET /api/charges/{id} funciona, pero obliga a estar preguntando. Si tienes un servidor, dile a Tilín a dónde avisarte y te llega en cuanto el pago entra.

Son dos pasos, una vez cada uno: el secreto con el que se firman tus avisos, y luego la dirección en cada cobro.

MétodoRutaQué hace
POST/api/account/webhook-secretGenera el secreto y lo devuelve una sola vez
DELETE/api/account/webhook-secretLo quita: dejas de poder pedir avisos
GET/api/account/webhook-eventsQué se te mandó y en qué quedó

1. El secreto

POST /api/account/webhook-secret
{ "secret": "whs_6f1d2c1e8a4b4e0b9a521f3d6c2b7e90...", "replaced": false, "algorithm": "sha256" }

Guárdalo: no hay forma de volver a leerlo. Es deliberado — si se pudiera, cualquier token robado serviría para aprender a falsificar avisos de "este cobro quedó pagado". Si lo pierdes, vuelve a llamar y se genera otro; replaced: true te avisa de que acabas de matar el anterior.

2. La dirección, en cada cobro

POST /api/charges
{ "amount": 60000, "reference": "PED-1082", "webhookUrl": "https://mi-app.com/tilin/aviso" }

Va cobro a cobro y no en los ajustes de la cuenta, porque es la pregunta del momento: el mismo negocio tiene un catálogo que quiere el aviso en un sitio y una caja que lo quiere en otro. La respuesta devuelve webhookUrl para que compruebes que llegó lo que mandaste — una URL con una errata no da ningún error, es una dirección válida que no contesta.

Sin secreto, el cobro se rechaza con 422 y te dice qué hacer. Es a propósito: aceptarlo dejaría el aviso fallando media hora más tarde, contigo mirando tu propio servidor.

3. Lo que te llega

Un POST con Content-Type: application/json:

{
  "id": "6f1d2c1e-8a4b-4e0b-9a52-1f3d6c2b7e90",
  "event": "charge.paid",
  "ref": "9x2mq7bn4k…",
  "created_at": "2026-11-17T14:02:11-05:00",
  "data": { "id": 1482, "status": "pagado", "amount": 60000, "payer": "JUAN PEREZ", "…": "…" }
}
CampoQué es
idEl del aviso. Con él reconoces un reintento: el mismo id es el mismo aviso
eventcharge.paid o charge.expired
refEl token del cobro
dataEl cobro, con la misma forma que GET /api/charges/{id}

Y estas cabeceras:

X-Tilin-Evento: charge.paid
X-Tilin-Id: 6f1d2c1e-8a4b-4e0b-9a52-1f3d6c2b7e90
X-Tilin-Fecha: 1763400131
X-Tilin-Firma: sha256=<hex>

4. Comprueba la firma. No es opcional

La dirección del aviso es pública: cualquiera que la conozca puede mandarte un POST diciendo que un cobro quedó pagado. Lo único que distingue el nuestro es la firma.

$cuerpo = file_get_contents('php://input');
$fecha  = (int) ($_SERVER['HTTP_X_TILIN_FECHA'] ?? 0);
$firma  = $_SERVER['HTTP_X_TILIN_FIRMA'] ?? '';

$esperada = 'sha256=' . hash_hmac('sha256', $fecha . '.' . $cuerpo, $TU_SECRETO);

// hash_equals y no ==: comparar cadenas con == filtra la respuesta por el tiempo que tarda
if (!hash_equals($esperada, $firma) || abs(time() - $fecha) > 300) {
    http_response_code(401);
    exit;
}

Las dos mitades importan:

5. Contesta rápido y con 2xx

Cualquier 2xx vale y nada más se mira. Lo que no sea 2xx —o no contestar en 10 segundos— se toma como que no llegó, y se reintenta a 1 min, 5 min, 30 min, 2 h y 12 h. Al sexto intento el aviso queda fallido y se ve en GET /api/account/webhook-events?status=fallido.

Contesta antes de hacer el trabajo: apunta el aviso, devuelve 200 y procesa después. Si tardas más de 10 segundos entregando el pedido, para nosotros no llegó y te lo volveremos a mandar.

Un reintento no es un pago nuevo. Puede llegarte el mismo aviso dos veces si tu 200 se perdió de vuelta; usa el id para reconocerlo.

6. Cuando no llega

GET /api/account/webhook-events?status=fallido
{
  "configured": true,
  "events": [
    { "id": "6f1d…", "event": "charge.paid", "ref": "9x2mq…", "status": "fallido",
      "attempts": 6, "last_status": 500, "last_error": "el socio respondió 500",
      "created_at": "2026-11-17T14:02:11-05:00", "sent_at": null,
      "payload": { "…": "el cuerpo exacto que se mandó" } }
  ]
}

Es lo que distingue "Tilín no lo mandó" de "mi servidor lo rechazó", que desde tu lado se ven igual. last_status es lo que contestó tu servidor y payload el cuerpo exacto que viajó.

Lo que conviene saber

Quién paga la comisión

Por omisión la comisión sale de tu saldo: el cliente paga $10.000, entran $10.000 y a fin de cuentas te quedan $9.680. Puedes darle la vuelta y sumarla al precio, como hace un datáfono: el cliente paga $10.330 y a ti te quedan los $10.000 limpios.

MétodoRutaQué hace
GET/api/fees/modeCómo está puesto, y un ejemplo con números
POST/api/fees/modeLo cambia

GET /api/fees/mode:

{
  "payer": "cliente",
  "round": 500,
  "steps": [0, 500, 1000],
  "fixed": 500,
  "percent": 2,
  "charged": true,
  "example": {
    "base": 10000,
    "merchantPays": { "customerPays": 10000, "youGet": 9300, "fee": 700 },
    "customerPays": { "customerPays": 10500, "youGet": 9790, "fee": 710 }
  }
}
CampoQué es
payercomercio (tú) o cliente
roundA qué múltiplo se redondea el total hacia arriba. 0 = sin redondear
stepsLos pasos que se admiten hoy. Pinta el selector desde aquí y no desde una lista copiada
chargedfalse si a tu cuenta no se le cobra nada. Entonces esto no hace nada
exampleLas dos opciones con números, para poder enseñárselas a alguien

POST /api/fees/mode con {"payer": "cliente", "round": 500}. Responde lo mismo que el GET, ya recalculado. Los dos campos son opcionales: se manda solo el que cambia.

Y cobro a cobro con feePayer en POST /api/charges, que manda sobre el ajuste de la cuenta. El caso real es mixto: en una venta de $3.000 sumarle $560 queda ridículo y en una de $200.000 no se nota.

La cuenta no es sumar la comisión

Es lo que parece y da un resultado corto. La comisión se calcula sobre el monto del cobro, y el monto del cobro va a ser el total, así que subirlo sube también la comisión. Con $10.000 y un 3,2%:

No tienes que hacerla tú: manda amount con lo que quieres recibir y feePayer: "cliente", y la respuesta trae amount (lo que paga el cliente), baseAmount (lo que recibes tú) y surcharge (la diferencia). Con esos tres puedes enseñarle el desglose al cliente.

El redondeo

round redondea el total hacia arriba al múltiplo que digas, para que el cliente no vea un número raro en el mostrador. Dos cosas que conviene saber antes de ponerlo en 1000:

Solo se aplica cuando la paga el cliente. Redondear el precio de quien no paga comisión sería cambiarle el precio sin que lo haya pedido.

Con payer: "cliente", el total del link es mayor que el precio de tu catálogo. Si la página enseña $10.000 y el link pide $10.500 sin explicarlo, el cliente va a pensar que algo está mal. Usa baseAmount y surcharge de la respuesta para enseñar el desglose, o deja el ajuste en comercio para el catálogo y pásala solo en los cobros del mostrador.

Direcciones de cobro

MétodoRutaQué hace
GET/api/mailboxesLas direcciones por las que se cobra, con el id de cada una

Es de donde sacas el mailboxId que le pasas a un cobro:

{
  "mailboxes": [
    { "id": 1, "address": "ventas@ejemplo.test", "label": "Ventas", "kind": "imap", "active": true, "hasOwnKey": false },
    { "id": 2, "address": "norte@ejemplo.test", "label": "Local norte", "kind": "imap", "active": true, "hasOwnKey": true }
  ]
}

Solo salen las que pueden recibir un pago. Si el negocio comparte el servicio con otros, el buzón del que se reparte el correo no es una de ellas y no aparece: ahí no se guarda el pago de nadie, así que un cobro atado a él no lo cerraría nunca.

hasOwnKey dice si esa dirección tiene su propia cuenta Nequi detrás. Si es false, los cobros que le mandes salen con la llave de la cuenta —la misma para todas—, así que ahí da igual cuál elijas. Con un token limitado, esta lista trae solo su dirección.

MétodoRutaQué hace
GET/c/{token}La página que abre quien va a pagar
GET/c/{token}/estado{"status": "pagado"} — lo que consulta esa página

No lleva token a propósito: la abre un cliente que no tiene cuenta. Lo que la protege es que el identificador es largo y aleatorio. La página solo enseña el monto, el negocio y el código; del comercio no sale nada más.

MétodoRutaQué hace
GET/api/qrSolo el contenido de un QR, sin guardar nada
POST/api/validate¿Entró un pago por este monto?
GET/api/transactionsLos movimientos
GET/api/statusBuzones, última sincronización, conteos

GET /api/qr?amount=50000&ref=MESA-4 — para enseñar un código en el mostrador:

{
  "payload": "00020101021226320014CO.COM.RBM.LLA0410@minegocio…63043CBB",
  "key": "@minegocio",
  "amount": 50000,
  "reference": "MESA-4",
  "anyBank": false
}

El dibujo lo hace tu programa con cualquier librería de QR. anyBank dice si lo lee la app de cualquier banco o solo Nequi, igual que en un cobro: ahí está explicado de dónde sale cada uno. No deja rastro: si quieres poder saber después si lo pagaron, usa un cobro.

POST /api/validate — cuando el cliente paga por su cuenta y tú solo compruebas:

curl -X POST https://tilinapp.online/api/validate \
  -H "Authorization: Bearer vb_tu_token" -H "Content-Type: application/json" \
  -d '{"amount": 50000, "withinMinutes": 60, "orderRef": "FACTURA-9"}'
{ "valid": false, "reason": "No hay un pago sin usar que coincida" }

Con orderRef, el pago encontrado queda marcado como usado por esa factura y no se puede validar dos veces. Es la defensa contra cobrar dos pedidos con el mismo pago.

GET /api/transactions — acepta kind (ingreso, gasto, propio), limit y mailbox (solo los de una dirección):

[{
  "id": 1,
  "kind": "ingreso",
  "date": "2026-10-07T18:41:08-05:00",
  "amount": 120000,
  "payer": "CLIENTE UNO",
  "channel": "Bre-B QR",
  "bank": "Nequi",
  "reference": "M77001122",
  "mailbox": "ventas@ejemplo.test",
  "claimed_by": "COBRO-47anrc847vjx6um98crmjm",
  "claimed_at": "2026-10-07T18:41:08-05:00"
}]

claimed_by dice si ese pago ya se usó: COBRO-… si cerró un link, o tu orderRef si lo validaste tú.

6. Cada cuánto preguntar

Con un token de cuenta, Tilín no llama a tu servidor: tu software pregunta. (Los avisos salientes existen solo para los socios, los programas que dan de alta cuentas: ver la sección 9.)

Con pocos clientes eso basta y no se nota.

7. Ejemplo completo (PHP)

<?php
const TILIN = 'https://tilinapp.online';
const TOKEN = 'vb_tu_token';

function tilin(string $metodo, string $ruta, ?array $cuerpo = null): array
{
    $ch = curl_init(TILIN . $ruta);
    $cabeceras = ['Authorization: Bearer ' . TOKEN, 'Accept: application/json',
                  'X-Timezone: America/Bogota'];
    if ($cuerpo !== null) {
        $cabeceras[] = 'Content-Type: application/json';
    }
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $metodo,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => $cabeceras,
        CURLOPT_TIMEOUT => 20,
    ]);
    if ($cuerpo !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($cuerpo));
    }
    $respuesta = json_decode((string) curl_exec($ch), true);
    $estado = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($estado >= 400) {
        throw new RuntimeException($respuesta['error'] ?? "HTTP {$estado}");
    }
    return $respuesta ?? [];
}

// Al facturar
$cobro = tilin('POST', '/api/charges', [
    'amount' => 120000,
    'reference' => 'SUSCRIPCION-' . date('Y-m'),
    'concept' => 'Plan mensual',
    'minutes' => 1440,
]);

guardarEnMiFactura($cobro['id'], $cobro['url'], $cobro['amount']);
// OJO: $cobro['amount'], no el que pediste
mandarPorWhatsapp($cliente, $cobro['url'], $cobro['amount']);

// Cada minuto, desde un cron
foreach (misFacturasEsperando() as $factura) {
    $cobro = tilin('GET', '/api/charges/' . $factura->tilinId);
    if ($cobro['status'] === 'pagado') {
        renovarSuscripcion($factura, $cobro['payer'], $cobro['payReference']);
    } elseif ($cobro['status'] === 'vencido') {
        marcarVencida($factura);  // y crear otro cobro si quieres reintentar
    }
}

8. Antes de salir a producción

9. Socios: dar de alta negocios desde otro programa

Para un directorio o una caja (Te Lo Tengo, por ejemplo) que quiere ofrecerle a sus negocios "cobrar con Nequi" sin mandarlos a registrarse en Tilín. El socio crea la cuenta desde su servidor en un toque, recibe el token de esa cuenta y desde ahí lo hace todo con la API de siempre (secciones 3 a 5). Tilín le avisa a su servidor cuando un cobro se paga o vence y cuando el alta de la cuenta avanza.

La llave del socio

La da el operador de Tilín desde la consola del servidor —no hay pantalla para esto, a propósito—:

php artisan tilin:socio crear "Te Lo Tengo" --webhook=https://telotengo.co/tilin/avisos --fijo=0 --porcentaje=0 --mensual=0

Enseña una sola vez la llave (tp_…) y el secreto con el que se firman los avisos (whs_…). En la base solo queda la huella de la llave. Va en cada llamada:

Authorization: Bearer tp_a1b2c3…

Sin llave, o con una que no vale, todo responde 401. La llave del socio solo abre las rutas de esta sección: no sirve para cobrar ni para leer pagos, y ningún token de cuenta abre estas rutas. Tampoco se le pide cabecera Origin: es para llamar de servidor a servidor.

Los --fijo, --porcentaje, --mensual y --limite son la tarifa con la que nacen las cuentas que cree ese socio. Se copia a la cuenta al crearla: cambiarla después no le sube el precio a las que ya existían.

Más comandos: tilin:socio listar, desactivar, activar, rotar-llave y editar (--webhook=…, --rotar-secreto, la tarifa).

Errores de esta sección

Además del error de siempre, traen un code en seco para que el programa decida sin leer frases:

{ "error": "Ese correo ya tiene una cuenta en Tilín…", "code": "cuenta_existente", "message": "Ese correo ya tiene una cuenta en Tilín…" }
codeEstadoQué pasa
no_autorizado401Falta la llave o no vale
ref_invalida422La ref admite letras, números y . _ : -, hasta 100
correo_invalido, falta_nombre422Faltan datos para crear
cuenta_existente409Ese correo ya es de una cuenta de Tilín. Ofrece vincularla
entrada_sin_configurar503Tilín no tiene montado el buzón de entrada
cuenta_no_existe404Al vincular: no hay cuenta activa con ese correo
cuenta_no_vinculable403Es una cuenta de administrador
ya_vinculada, ref_en_uso409La cuenta ya es tuya con otra ref, o esa ref es de otra cuenta
codigo_incorrecto422Trae attempts_left
codigo_vencido410Pasaron los 15 minutos
demasiados_intentos, demasiadas_peticiones429Cinco fallos, o demasiados códigos pedidos para esa cuenta
vinculo_usado409Ese código ya se usó
vinculo_no_existe, no_encontrada404No existe o es de otro socio (lo mismo, a propósito)

Rutas

MétodoRutaQué hace
POST/api/partner/accountsCrea la cuenta (o devuelve la que ya tenías con esa ref)
POST/api/partner/accounts/linkPide vincular una cuenta que ya existía: le llega un código al dueño
POST/api/partner/accounts/link/{link_id}/confirmConfirma con ese código
GET/api/partner/accounts/{ref}Cómo va esa cuenta
DELETE/api/partner/accounts/{ref}La suelta y revoca su token. No la borra
GET/api/partner/eventsLos avisos que se te mandaron, para depurar

POST /api/partner/accounts

curl -X POST https://tilinapp.online/api/partner/accounts \
  -H "Authorization: Bearer tp_tu_llave" -H "Content-Type: application/json" \
  -d '{"ref": "negocio-381", "email": "panaderia@ejemplo.co", "business_name": "Panadería La Espiga", "phone": "3001234567"}'
{
  "account_id": 42,
  "ref": "negocio-381",
  "address": "pg-k7m2xq9ad3@pagos.ejemplo.co",
  "step": "esperando",
  "token": "vb_9f3c…"
}

201 la primera vez. En una transacción: crea la cuenta, le da su dirección de pagos, le pone la tarifa del socio y emite su token. El nombre del negocio va también al QR (lo que ve quien paga), recortado a 25 caracteres; se cambia con POST /api/account/bre.

El token es un token por programa sin dirección de esa cuenta (sale en su panel como "Socio: Te Lo Tengo"): sirve para /api/account/inbound, /api/account/bre, /api/charges, /api/fees, /api/fees/mode, /api/qr y /api/qr/inspect, igual que el token de la cuenta. Es distinto del de la cuenta a propósito: si el dueño regenera el suyo desde el panel, el tuyo sigue vivo, y al revés.

Vincular una cuenta que ya existía

curl -X POST https://tilinapp.online/api/partner/accounts/link \
  -H "Authorization: Bearer tp_tu_llave" -H "Content-Type: application/json" \
  -d '{"ref": "negocio-77", "email": "dueno@ejemplo.co"}'
{ "link_id": "lk_4f0c2a9e1b7d3c5a8e6f0b12", "expires_at": "2026-11-16T15:27:00-05:00", "delivery": "registro" }

202. Le manda al dueño un código de 6 dígitos que vence a los 15 minutos. Él te lo dicta y tú lo confirmas:

curl -X POST https://tilinapp.online/api/partner/accounts/link/lk_4f0c2a9e1b7d3c5a8e6f0b12/confirm \
  -H "Authorization: Bearer tp_tu_llave" -H "Content-Type: application/json" -d '{"code": "482913"}'

Responde 200 con lo mismo que la creación (account_id, ref, address, token, step). Cinco intentos por código. Sin el código no hay vínculo: saber el correo de un negocio no basta para quedarse con su cuenta.

delivery dice por dónde salió el código: correo si el servidor tiene correo saliente configurado (MAIL_MAILER), o registro si no —entonces queda en Administración ▸ Registro del operador, y hay que pedírselo a él—. Vincular no cambia la tarifa de la cuenta; si la cuenta no tenía ninguna dirección por la que cobrar, se le da una.

GET /api/partner/accounts/{ref}

{
  "account_id": 42,
  "ref": "negocio-381",
  "address": "pg-k7m2xq9ad3@pagos.ejemplo.co",
  "step": "codigo",
  "code": "482913",
  "bre_ready": false,
  "fees": { "active": true, "balance": -2900, "blocked": false }
}
CampoQué es
stepEn qué va el alta. Ver abajo
codeEl código de verificación que llegó, mientras step sea codigo. Si no, null
bre_readySi ya tiene llave Bre-B o QR del banco: si ya puede cobrar con QR
feesSu saldo con el servicio. Con blocked: true los cobros con link responden 402

El alta, paso a paso (step, el mismo de GET /api/account/inbound):

stepQué significaQué le dices al negocio
sin-direccionNo tiene dirección de pagos—
esperandoLa tiene; falta ponerla en Nequi"En Nequi, cambia tu correo de notificaciones a address"
esperando-reenvioIgual, pero va a reenviar desde su correo"Reenvía desde tu correo a address"
codigoLlegó el código de verificación"Escribe code en Nequi"
confirmadoNequi confirmó el cambio de correo"Listo: el próximo pago ya se verá"
listoYa entró al menos un movimiento—

El código es el que manda Nequi a la dirección nueva al cambiar el correo de notificaciones (o el de Gmail al pedir un reenvío). Tilín lo atrapa porque le llega a él, comprueba que venga firmado por Nequi —igual que un pago— y lo enseña. Vale 30 minutos (INBOUND_CODE_MINUTES): pasado eso el paso vuelve a esperando y GET /api/account/inbound lo sigue devolviendo con "expired": true, para que se sepa que hay que pedir otro.

DELETE /api/partner/accounts/{ref} — {"ok": true, "ref": "…"}. La cuenta deja de ser tuya y el token que se te dio muere. No se borra nada: los pagos, la dirección y el saldo son del negocio.

Los avisos a tu servidor

Cuando pasa algo en una cuenta tuya, Tilín hace un POST a tu --webhook:

eventCuándodata
charge.paidUn cobro quedó pagadoEl cobro, con la misma forma de GET /api/charges/{id}
charge.expiredUn cobro venció sin pagarseÍdem
account.stepCambió el paso del alta{"step": "codigo", "previous": "esperando", "code": "482913"} (code solo en codigo)
{
  "id": "6f1d2c1e-8a4b-4e0b-9a52-1f3d6c2b7e90",
  "event": "charge.paid",
  "ref": "negocio-381",
  "created_at": "2026-11-16T15:12:04-05:00",
  "data": { "id": 1, "status": "pagado", "amount": 25000, "payer": "CLIENTE UNO" }
}

Cabeceras:

X-Tilin-Evento: charge.paid
X-Tilin-Id: 6f1d2c1e-8a4b-4e0b-9a52-1f3d6c2b7e90
X-Tilin-Fecha: 1763323924
X-Tilin-Firma: sha256=5d1c…

Comprueba la firma antes de creerte nada. Es el HMAC-SHA256, en hexadecimal, de "{X-Tilin-Fecha}.{cuerpo}" con tu secreto whs_…, sobre el cuerpo tal cual llegó (sin volver a serializarlo). Y descarta los que tengan una fecha de hace más de unos minutos: así un aviso capturado no se puede volver a mandar.

$cuerpo = file_get_contents('php://input');
$fecha  = $_SERVER['HTTP_X_TILIN_FECHA'] ?? '';
$firma  = 'sha256=' . hash_hmac('sha256', $fecha . '.' . $cuerpo, TILIN_SECRETO_AVISOS);
if (!hash_equals($firma, $_SERVER['HTTP_X_TILIN_FIRMA'] ?? '') || abs(time() - (int) $fecha) > 300) {
    http_response_code(401);
    exit;
}
$aviso = json_decode($cuerpo, true);
// $aviso['id'] es el mismo en cada reintento: úsalo para no procesarlo dos veces

Contesta cualquier 2xx y ya. Si no contestas, o contestas otra cosa, se reintenta a los 1 min, 5 min, 30 min, 2 h y 12 h; después queda fallido. Se reintenta con el mismo id y el mismo cuerpo, así que puede llegarte dos veces: compara por id.

Los avisos salen del cron de Tilín, que pasa cada minuto: cuenta con hasta un minuto o dos de retraso. No es el camino para la pantalla de la caja que espera un pago con el cliente delante —ahí pregunta por GET /api/charges/{id} cada pocos segundos—; es para que tu servidor se entere aunque nadie esté mirando. Un aviso que falla nunca afecta al cobro: el cobro ya quedó pagado.

GET /api/partner/events?status=fallido — los avisos que se te mandaron, lo último primero. status puede ser pendiente, enviado o fallido; limit hasta 200.

{
  "events": [{
    "id": "6f1d2c1e-8a4b-4e0b-9a52-1f3d6c2b7e90", "event": "charge.paid", "ref": "negocio-381",
    "status": "fallido", "attempts": 6, "next_at": null, "last_status": 500,
    "last_error": "el socio respondió 500", "created_at": "2026-11-16T15:12:04-05:00",
    "sent_at": null, "payload": { "id": "6f1d2c1e-8a4b-4e0b-9a52-1f3d6c2b7e90", "event": "charge.paid" }
  }]
}