Guías

Cobrar con un link de pago

Una URL corta que abre la pantalla de pago. Se manda por WhatsApp, se pega en una factura o se imprime como QR.

Un link de pago no necesita que tengas sitio web. Lo creas desde tu servidor, se lo pasas al comprador y Lane se encarga de cobrarle.

POST`/v1/payment_links`

Crea el link y devuelve su URL.

Cuerpo

Campo	Tipo	Obligatorio	Descripción
`amount`	entero	sí	En centavos. `11900000` son $ 119.000 COP.
`currency`	texto	no	Por defecto `COP`.
`description`	texto	no	Lo que ve el comprador en la pantalla de pago.
`expires_in`	entero	no	Segundos de vida del link. Por defecto `43200` (12 horas).
`multi_use`	booleano	no	`false` (por defecto) lo cierra después del primer pago. `true` lo deja abierto.
`max_uses`	entero	no	Cuántos pagos admite si `multi_use` es `true`. Omitido, no tiene tope.
`customer`	objeto	no	Datos del comprador. Con `email` alcanza para que quede asociado a un cliente.
`metadata`	objeto	no	Lo que quieras guardar. Vuelve intacto en el cobro y en el webhook.

Crear un link

curl -X POST https://gxxazsplhgyezwxghrnn.supabase.co/functions/v1/blink-api/v1/payment_links \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4890000,
    "currency": "COP",
    "description": "Pedido #4821",
    "expires_in": 86400,
    "customer": { "email": "cliente@ejemplo.com" },
    "metadata": { "order_id": "4821" }
  }'

const res = await fetch("https://gxxazsplhgyezwxghrnn.supabase.co/functions/v1/blink-api/v1/payment_links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LANE_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 4_890_000,          // $ 48.900 COP
    currency: "COP",
    description: "Pedido #4821",
    expires_in: 86_400,         // 24 horas
    customer: { email: "cliente@ejemplo.com" },
    metadata: { order_id: "4821" },
  }),
});

const { checkout_url, payment } = await res.json();
// Guarda payment.id contra tu pedido: es como vas a reconocer el webhook.

Respuesta 201

{
  "id": "3f0c8a1e-…",
  "object": "checkout.session",
  "environment": "test",
  "amount": 4890000,
  "currency": "COP",
  "status": "pending",
  "checkout_url": "https://lane.money/l/a7Kd2",
  "payment": { "id": "9b41d0c7-…", "status": "pending" }
}

Guarda `payment.id`, no solo la URL. El webhook llega con el identificador del cobro. Si no lo guardaste contra tu pedido, vas a recibir un aviso de que alguien pagó sin saber qué.

Un link para varios pagos

Por defecto el link se cierra con el primer pago. Para un QR pegado en el mostrador o un cobro de inscripción que muchas personas pagan, ábrelo con multi_use.

Link reutilizable con tope

{
  "amount": 15000000,
  "description": "Inscripción torneo",
  "multi_use": true,
  "max_uses": 40,
  "expires_in": 604800
}

Refrescar el estado

Si el webhook no llegó o quieres reconciliar a mano, pide una sincronización del link contra el procesador.

POST`/v1/payment_links/{id}/sync`

Vuelve a leer el estado del link y actualiza el cobro.

Sincronizar

curl -X POST "https://gxxazsplhgyezwxghrnn.supabase.co/functions/v1/blink-api/v1/payment_links/3f0c8a1e-…/sync" \
  -H "Authorization: Bearer sk_test_…"

La pantalla de pago

El checkout_url abre una página de Lane con el nombre del negocio, el monto y el detalle del cobro. Hoy su apariencia no es configurable por API: el comercio que aparece y el logo salen de lo que cargaste en el panel.

Para cobrar con PSE, Nequi, Daviplata o Bre-B en vez de tarjeta, mira Medios instantáneos.

Esta página en markdown: /docs/guias/link-de-pago.md · Toda la documentación: /docs/llms-full.txt