# Cobros

> Referencia del recurso payments de Lane: crear un cobro con tarjeta guardada, consultarlo, listarlo, capturar, anular, ajustar y reembolsar.

El objeto central de la API. Todo lo demás existe para crear uno o para entenderlo.

_Recorrido de un cobro: pending → authorized → processing → succeeded, o failed / cancelled / refunded. Esta sección documenta el estado `authorized`._

## Crear un cobro

### POST /v1/payments

Cobra contra una tarjeta ya guardada. Para cobrar con el comprador presente, usa una [sesión de checkout](https://lane.money/docs/api/sesiones).

**Cuerpo**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `amount` | entero | sí | En centavos. Cero solo con `intent: "account-status"`. |
| `currency` | texto | no | Por defecto `COP`. |
| `instrument_id` | UUID | condicional | La tarjeta guardada en Lane. Obligatorio si no mandas `provider_instrument_id`; no mandes los dos. |
| `provider_instrument_id` | texto | condicional | El identificador de la tarjeta en el procesador, para migraciones. |
| `initiator` | `customer` · `merchant` | no | Quién dispara el cobro. Por defecto `merchant`. |
| `cvv` | texto | condicional | 3 o 4 dígitos. Obligatorio con `initiator: "customer"`, prohibido con `merchant`. |
| `order_type` | texto | no | El tipo de orden para la red. Ver [Cobro recurrente](https://lane.money/docs/guias/cobro-recurrente). |
| `intent` | `authorization` · `pre-authorization` · `account-status` | no | Por defecto `authorization`. |
| `capture` | objeto | no | `{ "mode": "AUTOMATIC" \| "MANUAL" \| "SCHEDULED" }`. Manual deja el cobro en `authorized`. |
| `installments` | objeto | no | `{ "quantity": 3 }`, mínimo 2. Omítelo para un pago sin cuotas. |
| `parent_transaction_data` | objeto | condicional | Enlace al primer cobro de la serie. Obligatorio en cobros recurrentes sin el cliente presente. |
| `metadata` | objeto | no | Vuelve intacto en el cobro y en el webhook. |

**Cobrar una tarjeta guardada**

```bash
curl -X POST https://gxxazsplhgyezwxghrnn.supabase.co/functions/v1/blink-api/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 8900000,
    "currency": "COP",
    "instrument_id": "c1a9f3e0-…",
    "initiator": "merchant",
    "order_type": "recurring",
    "parent_transaction_data": { "first_payment_id": "9b41d0c7-…" }
  }'
```

_Respuesta 200_

```json
{
  "object": "payment",
  "id": "a02e5b19-…",
  "amount": 8900000,
  "currency": "COP",
  "status": "succeeded",
  "status_detail": "CAPTURED",
  "payment_method": "CARD",
  "processed_at": "2026-09-06T18:22:41.000Z"
}
```

## Consultar un cobro

### GET /v1/payments/{id}

Devuelve el cobro con su estado actual.

**Query**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `sync` | booleano | no | `true` consulta al procesador antes de responder. Más lento; para depurar. |

**Consultar**

```bash
curl "https://gxxazsplhgyezwxghrnn.supabase.co/functions/v1/blink-api/v1/payments/a02e5b19-…" \
  -H "Authorization: Bearer sk_test_…"
```

_Respuesta 200_

```json
{
  "object": "payment",
  "id": "a02e5b19-…",
  "amount": 8900000,
  "currency": "COP",
  "status": "succeeded",
  "status_detail": "CAPTURED",
  "payment_method": "CARD",
  "customer_id": "44f1…",
  "checkout_session_id": null,
  "metadata": { "order_id": "4821" },
  "cleared_at": "2026-09-07T04:00:00.000Z",
  "processed_at": "2026-09-06T18:22:41.000Z",
  "created_at": "2026-09-06T18:22:39.000Z"
}
```

## Listar cobros

### GET /v1/payments

Los cobros del entorno de la llave, del más nuevo al más viejo.

**Query**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `status` | texto | no | Uno o varios separados por coma: `succeeded,refunded`. |
| `customer_id` | UUID | no | Solo los de ese cliente. |
| `created_after` | fecha | no | ISO 8601. Desde esa fecha en adelante. |
| `limit` | entero | no | Por defecto 25, máximo 100. |
| `starting_after` | cursor | no | El `next_cursor` de la página anterior. |

**Cobros aprobados de esta semana**

```bash
curl "https://gxxazsplhgyezwxghrnn.supabase.co/functions/v1/blink-api/v1/payments?status=succeeded&created_after=2026-09-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer sk_test_…"
```

_Respuesta 200_

```json
{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "object": "payment",
      "id": "a02e5b19-…",
      "amount": 8900000,
      "currency": "COP",
      "status": "succeeded",
      "payment_method": "CARD",
      "created_at": "2026-09-06T18:22:39.000Z"
    }
  ]
}
```

## Operar sobre un cobro

Las cinco operaciones son `POST` sin cuerpo obligatorio. Un reembolso o un ajuste parcial admiten `{ "amount": … }` en centavos; sin ese campo, la operación es por el total.

| Ruta | Requiere | Deja el cobro en |
| --- | --- | --- |
| `POST /v1/payments/{id}/capture` | `authorized` | `succeeded` |
| `POST /v1/payments/{id}/cancel` | `authorized` | `cancelled` |
| `POST /v1/payments/{id}/adjust` | `authorized` | `authorized`, con otro monto |
| `POST /v1/payments/{id}/refund` | `succeeded` | `refunded` |
| `POST /v1/payments/{id}/cancel-or-refund` | `authorized` o `succeeded` | Según cuál fuera |

**Reembolso parcial**

```bash
curl -X POST "https://gxxazsplhgyezwxghrnn.supabase.co/functions/v1/blink-api/v1/payments/a02e5b19-…/refund" \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 2000000 }'
```

> **Cuidado: Solo la tarjeta se devuelve.** Un cobro por PSE, Nequi, Daviplata o Bre-B no admite `refund` ni `cancel`. Ver [Medios instantáneos](https://lane.money/docs/guias/medios-instantaneos).