Conceptos

El recorrido de un cobro

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 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í

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.

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.

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

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

Respuesta 200

{
  "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"
}

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