Links de pago

La forma más directa de cobrar: creas un link con monto y descripción, se lo mandas al cliente y él paga en una página segura de TipTap Go.

Crear un link

POST/v1/payment_links

Cuerpo

Campo	Tipo	Descripción
`title`obligatorio	string	Lo que ve el cliente en la página de cobro. 2–120 caracteres.
`amount`obligatorio	number	Monto a cobrar, mayor a 0 (ej. 25.50).
`description`	string	Detalle opcional debajo del título (máx. 300).
`max_uses`	integer \| null	Si lo omites, el link es de un solo uso. Con un número, admite esa cantidad de pagos aprobados. Con `null`, usos ilimitados (útil para una donación o un QR fijo).
`expires_at`	ISO-8601	Vencimiento. Por defecto, 30 días desde la creación.
`metadata`	object	Datos tuyos que te devolvemos tal cual (id de orden, sucursal, vendedor…). No lo ve el cliente.

curl

curl -X POST https://go.paytiptap.com/api/v1/payment_links \
  -H "Authorization: Bearer tiptap_sk_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Orden #1042",
    "description": "2 tortas + delivery",
    "amount": 45.90,
    "expires_at": "2026-08-01T23:59:00Z",
    "metadata": { "orden_id": "1042", "sucursal": "vía españa" }
  }'

201 Created

{
  "object": "payment_link",
  "id": "cms1262i00001j59ysc8yio8u",
  "url": "https://go.paytiptap.com/pay/sQ9sUDRRCVV8",
  "title": "Orden #1042",
  "description": "2 tortas + delivery",
  "amount": 45.9,
  "currency": "USD",
  "status": "ACTIVE",
  "max_uses": 1,
  "paid_count": 0,
  "expires_at": "2026-08-01T23:59:00.000Z",
  "metadata": { "orden_id": "1042", "sucursal": "vía españa" },
  "created_at": "2026-07-26T00:27:04.104Z"
}

Guarda el id junto a tu orden

Como la API todavía no tiene idempotency keys, guarda el id del link en tu orden. Así, si tu proceso se cae a mitad, sabes si ya lo habías creado en vez de crear uno duplicado.

Estados del link

Campo	Tipo	Descripción
`ACTIVE`	string	Se puede pagar.
`COMPLETED`	string	Alcanzó su cupo (`paid_count === max_uses`). Ya no admite pagos.
`CANCELLED`	string	Lo cancelaste tú (por API o desde el panel).

Un link vencido (expires_at pasado) sigue con estado ACTIVE pero la página de cobro lo rechaza. Considera vencido cualquier link cuyo expires_at ya pasó.

Consultar y listar

GET/v1/payment_links/{id}

GET/v1/payment_links

Filtros: status, created_after, created_before, más la paginación por cursor.

curl

curl "https://go.paytiptap.com/api/v1/payment_links?status=ACTIVE&limit=50" \
  -H "Authorization: Bearer tiptap_sk_TU_LLAVE"

Cancelar

POST/v1/payment_links/{id}/cancel

Cierra el link para nuevos pagos. Es idempotente: cancelar dos veces devuelve 200 con el link ya cancelado. Si el link ya estaba COMPLETED responde 409 link_completed. Cancelar no devuelve el dinero de los pagos ya cobrados.

curl

curl -X POST https://go.paytiptap.com/api/v1/payment_links/cms1262i00001j59ysc8yio8u/cancel \
  -H "Authorization: Bearer tiptap_sk_TU_LLAVE"

Saber si te pagaron

Dos caminos, y conviene tener los dos:

Webhook payment.succeeded — llega en cuanto se aprueba el cobro. Es el camino principal. Ver webhooks.
Consulta — GET /v1/payments?payment_link_id=… o simplemente mira paid_count en el link. Sirve de respaldo por si tu servidor estuvo caído.

¿Está pagado este link?

const res = await fetch(
  `https://go.paytiptap.com/api/v1/payments?payment_link_id=${linkId}&status=APPROVED&limit=1`,
  { headers: { Authorization: `Bearer ${process.env.TIPTAP_API_KEY}` } }
);
const { data } = await res.json();
const pagado = data.length > 0;

Cobros que se repiten

Para una mensualidad, crea un link por período (con metadata apuntando al período) o, mejor, guarda la tarjeta del cliente una sola vez y cóbrale sin que tenga que hacer nada: ver clientes y tarjeta guardada.

← Integrar con un agente de IA Clientes y tarjeta guardada →