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:
- cobra siempre a esa cuenta Nequi, aunque el programa mande otra en el cuerpo;
- solo ve los cobros y los movimientos de esa dirección;
- no puede tocar los ajustes de la cuenta, ni los teléfonos, ni emitir más tokens;
- se quita sin que los demás se enteren.
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
| Formato | JSON en ambos sentidos. En los POST, manda Content-Type: application/json |
| Montos | Números en pesos colombianos. 120000 son ciento veinte mil |
| Fechas | ISO 8601 con zona: 2026-10-07T18:41:08-05:00 |
| Zona horaria | Por omisión la del servidor. Mándala con la cabecera X-Timezone: America/Bogota y las fechas te llegan en esa |
| Errores | Siempre {"error": "explicación en español"}, pensada para poder enseñársela a una persona |
Códigos que vas a ver:
200/201— bien.401— falta el token o no vale.402— tu saldo con el servicio se pasó del límite y los cobros con link están cortados. Recarga y vuelve a intentarlo; elerrordice cuánto debes. Ver Tu saldo con el servicio.404— no existe, o es de otra cuenta (es lo mismo a propósito: así no se puede averiguar qué ids existen).422— los datos no valen; elerrordice por qué.429— demasiados intentos seguidos; espera y reintenta.500— fallo del servidor. Trae una referencia (ref. a3f91c) que el administrador puede buscar en el registro del panel.
3. El flujo normal: cobrar con link
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étodo | Ruta | Qué hace |
|---|---|---|
POST | /api/charges | Crea un cobro. Devuelve 201 |
GET | /api/charges/{id} | Un cobro y su estado |
GET | /api/charges | El historial |
POST | /api/charges/{id}/cancel | Anula uno pendiente |
POST /api/charges — campos del cuerpo:
| Campo | Obligatorio | Qué es |
|---|---|---|
amount | sí | El monto. Mayor que cero |
reference | no | Tu referencia, hasta 25 caracteres (SUSCRIPCION-OCT). Sale en el panel y en el comprobante |
concept | no | Para qué es, hasta 190 caracteres. Se le enseña al cliente |
minutes | no | Cuánto vive el link. Por omisión, lo configurado en la cuenta |
mailboxId | no | A qué cuenta Nequi se le cobra. Los ids salen de GET /api/mailboxes. Con un token limitado se ignora: cobra siempre a la suya |
webhookUrl | no | A dónde avisarte cuando este cobro quede pagado (o venza). https://. Hace falta el secreto de la cuenta — ver abajo |
feePayer | no | Quié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:
| Campo | Qué es |
|---|---|
id | El que guardas tú para preguntar después |
token, url | El link que se le manda al cliente |
amount | Lo que hay que pagar (puede traer el ajuste) |
reference, concept | Lo que mandaste al crearlo, tal cual. null si no mandaste nada |
requested, bump | Lo pedido y lo sumado. Solo al crearlo |
status | pendiente · pagado · vencido · anulado |
mailboxId, mailbox | A qué dirección se le cobró: el id y su nombre. null si el cobro es de la cuenta y no de un local |
payload | El contenido del QR, por si lo dibujas tú. Ya lleva el valor dentro |
key | La llave Bre-B que lleva dentro ese código, para ofrecer una transferencia |
anyBank | true si el código lo lee la app de cualquier banco; false si solo Nequi. Ver abajo |
fee | Lo que te costó de comisión del servicio. null mientras no esté pagado, y null siempre si no tienes tarifa |
feePayer | comercio o cliente. No confundir con payer, que es quién pagó |
baseAmount | Lo que vas a recibir tú, si la comisión va encima. null si la pagas tú |
surcharge | Lo que se le sumó al precio. null si la pagas tú |
webhookUrl | A dónde se avisará de este cobro, si lo pediste al crearlo. null si no |
createdAt, expiresAt, paidAt | Fechas con zona |
payer | Quién pagó, tal como lo manda el banco |
payReference, payBank | Comprobante 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.
anyBank | De dónde sale | Quién lo lee |
|---|---|---|
true | Del QR de comercio del banco del negocio, con el importe insertado | La app de cualquier banco |
false | Armado con la llave del negocio | Solo 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:
- Cada cobro con link que te paguen descuenta una comisión: unos pesos fijos más un porcentaje. Solo se devenga cuando el cobro llega a pagarse — un link que nadie paga no cuesta nada. Los QR al momento (
/api/qr) no descuentan nada. - La cuota del servicio, si la tienes, se carga una vez al mes el mismo día en que te dieron de alta (
monthlyDay).
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étodo | Ruta | Qué hace |
|---|---|---|
GET | /api/fees | Tu saldo, tu tarifa y tu extracto |
POST | /api/fees/topup | Prepara 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 }
]
}
| Campo | Qué es |
|---|---|
balance | Tu saldo. Positivo es saldo a favor; negativo es lo que debes |
debt | Lo que debes, en positivo, para no tener que darle la vuelta al signo |
limit | Hasta cuánto se te fía. null = no se te corta nunca; 0 = prepago puro |
blocked, blockedReason | Si tienes los cobros con link cortados, y el motivo en palabras |
fixed, percent | Tu tarifa por cobro con link, para que puedas rehacer la cuenta de cualquier transacción |
monthly, monthlyDay | La cuota del servicio y el día del mes en que se te carga. 0 y null si no tienes cuota |
suggested | Lo que te proponemos recargar: lo que debes, redondeado hacia arriba |
ledger | Los ú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étodo | Ruta | Qué hace |
|---|---|---|
POST | /api/admin/users/{id}/fees/topup | Prepara 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étodo | Ruta | Qué hace |
|---|---|---|
POST | /api/account/webhook-secret | Genera el secreto y lo devuelve una sola vez |
DELETE | /api/account/webhook-secret | Lo quita: dejas de poder pedir avisos |
GET | /api/account/webhook-events | Qué 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", "…": "…" }
}
| Campo | Qué es |
|---|---|
id | El del aviso. Con él reconoces un reintento: el mismo id es el mismo aviso |
event | charge.paid o charge.expired |
ref | El token del cobro |
data | El 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:
- La firma sobre
{fecha}.{cuerpo}, con el cuerpo tal como llegó, byte a byte. Si lo decodificas y lo vuelves a serializar, la firma no cuadrará. - La fecha, que va dentro de lo firmado. Sin comprobar que es de hace poco, un aviso capturado se puede volver a mandar dentro de un mes y seguiría verificando.
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
https://obligatorio, salvohttp://localhostpara probar. El aviso dice quién te pagó y cuánto; por HTTP eso viaja legible por cualquier red por la que pase.- No se siguen redirecciones. El aviso va a la dirección que diste.
- La dirección se congela al crear el cobro. Cambiarla después no mueve los avisos que ya estaban en cola: un reintento tiene que ir a donde fue el primer intento.
- Solo avisa de cobros con link. Un pago que entra a tu dirección Bre-B sin un cobro que lo espere no genera aviso, porque no hay cobro del que hablar. Para enterarte de esos, pregunta por
GET /api/transactions. - Si además estás vinculado a un socio, los avisos son dos y no uno: el del socio a su dirección y el tuyo a la del cobro, cada uno firmado con su propio secreto.
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étodo | Ruta | Qué hace |
|---|---|---|
GET | /api/fees/mode | Cómo está puesto, y un ejemplo con números |
POST | /api/fees/mode | Lo 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 }
}
}
| Campo | Qué es |
|---|---|
payer | comercio (tú) o cliente |
round | A qué múltiplo se redondea el total hacia arriba. 0 = sin redondear |
steps | Los pasos que se admiten hoy. Pinta el selector desde aquí y no desde una lista copiada |
charged | false si a tu cuenta no se le cobra nada. Entonces esto no hace nada |
example | Las 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%:
- mal:
10.000 + 320 = 10.320→ la comisión real son 330 → te quedan 9.990 - bien:
10.000 / (1 - 0,032) = 10.331→ comisión 331 → te quedan 10.000 justos
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:
- Lo que sobra es tuyo. Con $10.000 y un 3,2%, el total exacto es 10.331; redondeado a 500 son 10.500, la comisión sube a 336 y te quedan 10.164. El redondeo nunca te deja por debajo de lo que pediste.
- Un precio que ya es redondo sube un paso entero. Con
round: 1000, un cobro de $10.000 pide $11.000, porque 10.331 ya pasó de 10.000. Si cobras cifras redondas,500suele ser lo que quieres.
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.
Si publicas un catálogo
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étodo | Ruta | Qué hace |
|---|---|---|
GET | /api/mailboxes | Las 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.
La página del link (pública, sin token)
| Método | Ruta | Qué 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.
Si prefieres no usar links
| Método | Ruta | Qué hace |
|---|---|---|
GET | /api/qr | Solo el contenido de un QR, sin guardar nada |
POST | /api/validate | ¿Entró un pago por este monto? |
GET | /api/transactions | Los movimientos |
GET | /api/status | Buzones, ú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.)
- Mientras tengas cobros pendientes, cada 30–60 segundos. Una sola llamada a
GET /api/charges?status=pendientete los trae todos, aunque tengas varios abiertos. - Sin cobros pendientes, no preguntes.
- Un cobro vencido ya no va a cambiar: sácalo de tu lista de espera.
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
PUBLIC_BASE_URLtiene que estar puesto en el.envdel servidor: es de donde sale elurldel cobro. Sin él se usa el dominio por el que entró la petición.- La cuenta necesita su llave Bre-B (Panel ▸ Mi cuenta ▸ Cobros con QR). Sin ella,
POST /api/chargesresponde422. - Dale a cada programa su propio token (Panel ▸ Mi cuenta ▸ Tokens por programa) en vez del de la cuenta. Si el negocio tiene varias cuentas Nequi, átalo a la dirección que le toca: así un error de ese programa no le cobra al local de al lado, y quitarlo no tumba a los demás.
- Prueba el ciclo entero con un cobro de $100 pagado de verdad antes de conectarlo a tus clientes. Es la única forma de ver que el correo del banco llega y se concilia. Con varias cuentas Nequi, uno por cada una: es lo que confirma que cada QR le cobra a la suya.
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…" }
code | Estado | Qué pasa |
|---|---|---|
no_autorizado | 401 | Falta la llave o no vale |
ref_invalida | 422 | La ref admite letras, números y . _ : -, hasta 100 |
correo_invalido, falta_nombre | 422 | Faltan datos para crear |
cuenta_existente | 409 | Ese correo ya es de una cuenta de Tilín. Ofrece vincularla |
entrada_sin_configurar | 503 | Tilín no tiene montado el buzón de entrada |
cuenta_no_existe | 404 | Al vincular: no hay cuenta activa con ese correo |
cuenta_no_vinculable | 403 | Es una cuenta de administrador |
ya_vinculada, ref_en_uso | 409 | La cuenta ya es tuya con otra ref, o esa ref es de otra cuenta |
codigo_incorrecto | 422 | Trae attempts_left |
codigo_vencido | 410 | Pasaron los 15 minutos |
demasiados_intentos, demasiadas_peticiones | 429 | Cinco fallos, o demasiados códigos pedidos para esa cuenta |
vinculo_usado | 409 | Ese código ya se usó |
vinculo_no_existe, no_encontrada | 404 | No existe o es de otro socio (lo mismo, a propósito) |
Rutas
| Método | Ruta | Qué hace |
|---|---|---|
POST | /api/partner/accounts | Crea la cuenta (o devuelve la que ya tenías con esa ref) |
POST | /api/partner/accounts/link | Pide vincular una cuenta que ya existía: le llega un código al dueño |
POST | /api/partner/accounts/link/{link_id}/confirm | Confirma 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/events | Los 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.
refes tu identificador del negocio, y es lo que hace idempotente el alta: repetir con la mismarefdevuelve200con la misma cuenta y"token": null(ya se te dio). Con"rotate_token": truesale uno nuevo y el anterior muere en ese momento.- Si el
emailya tiene cuenta en Tilín:409 cuenta_existente. Ofrécele vincularla. - La cuenta nace sin contraseña que nadie conozca: el negocio vive en tu app y no necesita entrar al panel de Tilín. Si algún día lo necesita, el operador le pone una con
php artisan tilin:clave. Tilín no tiene "olvidé mi contraseña".
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 }
}
| Campo | Qué es |
|---|---|
step | En qué va el alta. Ver abajo |
code | El código de verificación que llegó, mientras step sea codigo. Si no, null |
bre_ready | Si ya tiene llave Bre-B o QR del banco: si ya puede cobrar con QR |
fees | Su 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):
step | Qué significa | Qué le dices al negocio |
|---|---|---|
sin-direccion | No tiene dirección de pagos | — |
esperando | La tiene; falta ponerla en Nequi | "En Nequi, cambia tu correo de notificaciones a address" |
esperando-reenvio | Igual, pero va a reenviar desde su correo | "Reenvía desde tu correo a address" |
codigo | Llegó el código de verificación | "Escribe code en Nequi" |
confirmado | Nequi confirmó el cambio de correo | "Listo: el próximo pago ya se verá" |
listo | Ya 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:
event | Cuándo | data |
|---|---|---|
charge.paid | Un cobro quedó pagado | El cobro, con la misma forma de GET /api/charges/{id} |
charge.expired | Un cobro venció sin pagarse | Ídem |
account.step | Cambió 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" }
}]
}