# El recorrido de un cobro

> Los siete estados por los que pasa un pago en Lane: pending, authorized, processing, succeeded, failed, cancelled y refunded. Cuál es final y cuál no.

Un cobro es una máquina de estados. Saber en cuál está te dice qué puedes hacer con él.

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

El campo `status` aparece en todas las respuestas de pago y es el mismo vocabulario en toda la API: en el objeto que devuelve un cobro, en el listado y en el nombre del evento del webhook (`payment.succeeded`, `payment.failed`).

## Los siete estados

| Estado | Qué pasó | ¿Final? |
| --- | --- | --- |
| `pending` | El cobro existe pero nadie lo ha pagado todavía. Es el estado en el que nace. | No |
| `authorized` | El emisor reservó la plata, pero aún no se cobró. Solo ocurre con captura manual. | No |
| `processing` | La captura está en curso. No hace falta hacer nada: va a resolverse sola. | No |
| `succeeded` | Aprobado. Es el único estado en el que puedes despachar. | Sí |
| `failed` | El emisor rechazó. La plata nunca se movió. | Sí |
| `cancelled` | Se anuló antes de capturar. Se liberó la reserva. | Sí |
| `refunded` | Se devolvió la plata al comprador, total o parcialmente. | Sí |

> **Importante: Despacha solo en `succeeded`.** Volver a tu `success_url` no significa que el cobro se aprobó: significa que el comprador volvió. La única fuente de verdad es el `status` del cobro, y la forma correcta de conocerlo es el [webhook](https://lane.money/docs/webhooks).

## Qué se puede hacer en cada estado

| Operación | Estado requerido | Resultado |
| --- | --- | --- |
| `POST /v1/payments/{id}/capture` | `authorized` | Cobra la plata reservada → `succeeded` |
| `POST /v1/payments/{id}/cancel` | `authorized` | Libera la reserva → `cancelled` |
| `POST /v1/payments/{id}/adjust` | `authorized` | Cambia el monto antes de capturar |
| `POST /v1/payments/{id}/refund` | `succeeded` | Devuelve la plata → `refunded` |
| `POST /v1/payments/{id}/cancel-or-refund` | `authorized` o `succeeded` | Elige la operación correcta según el estado |

Si no sabes en cuál de los dos está —porque la captura fue automática y pasó rápido— usa `cancel-or-refund` y deja que el servidor decida. Es una llamada menos y no puede equivocarse.

## Compensado no es liquidado

Un cobro `succeeded` puede traer `cleared_at`: la fecha en que la red compensó la transacción. **No es la fecha en la que la plata cae en tu cuenta.** El depósito depende del calendario de liquidación de tu comercio, y la API no lo expone.

## Los medios instantáneos no se devuelven

PSE, Nequi, Daviplata y Bre-B mueven la plata en el momento y son irrevocables: un cobro por esos medios no admite `refund` ni `cancel`. Para devolver el dinero tienes que hacer una transferencia aparte al comprador. Está explicado en [Medios instantáneos](https://lane.money/docs/guias/medios-instantaneos).

## Forzar una actualización

Consultar un cobro lee lo que Lane tiene guardado. Si sospechas que quedó atrás, agrega `?sync=true` y se consulta contra el procesador antes de responder. Es más lento; úsalo para depurar, no en cada carga de página.

**Consultar sincronizando**

```bash
curl "https://gxxazsplhgyezwxghrnn.supabase.co/functions/v1/blink-api/v1/payments/9b41d0c7-…?sync=true" \
  -H "Authorization: Bearer sk_test_…"
```

_Respuesta 200_

```json
{
  "object": "payment",
  "id": "9b41d0c7-…",
  "amount": 11900000,
  "currency": "COP",
  "status": "succeeded",
  "status_detail": "CAPTURED",
  "payment_method": "CARD",
  "cleared_at": "2026-09-07T04:00:00.000Z",
  "processed_at": "2026-09-06T18:22:41.000Z"
}
```