# Sesiones y links

> Referencia de las sesiones de checkout, los links de pago y las sesiones de inscripción de tarjeta en la API de Lane.

Tres endpoints que crean una pantalla de pago. Comparten casi todo el contrato.

## Sesión de checkout

### POST /v1/checkout/sessions

Crea la pantalla de pago y devuelve su URL. Responde `201`.

**Cuerpo**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `amount` | entero | sí | En centavos, mayor que cero. |
| `currency` | texto | no | Por defecto `COP`. |
| `description` | texto | no | Lo que ve el comprador. |
| `payment_method` | `pse` · `nequi` · `daviplata` · `breb` | no | Omitido, el cobro es con tarjeta. Ver [Medios instantáneos](https://lane.money/docs/guias/medios-instantaneos). |
| `success_url` | URL | no | Admite `{PAYMENT_ID}` y `{CHECKOUT_SESSION_ID}`. |
| `cancel_url` | URL | no | A dónde vuelve si abandona. |
| `error_url` | URL | no | A dónde vuelve si el emisor rechaza. |
| `customer` | objeto | no | Con `email` queda asociado a un cliente. |
| `line_items` | lista | no | El detalle del carrito. |
| `metadata` | objeto | no | Vuelve intacto en el cobro y en el webhook. |
| `expires_in` | entero | no | Segundos de vida. Por defecto `43200` (12 horas). |
| `multi_use` | booleano | no | `true` deja la pantalla abierta para varios pagos. |
| `max_uses` | entero | no | Tope de pagos cuando `multi_use` es `true`. |
| `checkout_options` | objeto | no | `require_3ds`, `allow_installments`, `additional_fields`. |

**Respuesta**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | UUID | no | La sesión. |
| `status` | texto | no | Nace en `pending`. |
| `checkout_url` | URL | no | A dónde mandas al comprador. |
| `embed_url` | URL | no | La misma URL, para usar como `src` de un iframe. |
| `payment` | objeto | no | `{ id, status }` del cobro asociado. **Guarda este `id`**: es el que llega en el webhook. |
| `environment` | `test` · `live` | no | El entorno de la llave con la que creaste la sesión. |

## Link de pago

### POST /v1/payment_links

Mismo contrato que la sesión de checkout. La diferencia es de uso, no de forma: un link se manda, una sesión se enlaza desde un carrito.

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

Relee el estado del link contra el procesador y actualiza el cobro.

## Sesión de inscripción

### POST /v1/enrollment/sessions

Crea la pantalla donde el cliente guarda su tarjeta, sin cobrar nada.

**Cuerpo**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `customer` | objeto | no | De quién es la tarjeta. |
| `success_url` | URL | no | A dónde vuelve cuando termina. |
| `cancel_url` | URL | no | A dónde vuelve si abandona. |
| `expires_in` | entero | no | Entre 60 y 86400 segundos. |
| `metadata` | objeto | no | Vuelve en el instrumento. |

**Inscribir una tarjeta**

```bash
curl -X POST https://gxxazsplhgyezwxghrnn.supabase.co/functions/v1/blink-api/v1/enrollment/sessions \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "email": "cliente@ejemplo.com" },
    "success_url": "https://mitienda.com/tarjeta-guardada"
  }'
```

_Respuesta 201_

```json
{
  "id": "7d2b…",
  "object": "enrollment.session",
  "environment": "test",
  "status": "pending",
  "enrollment_url": "https://…",
  "embed_url": "https://…"
}
```