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`	Solo en una preautorización (`capture.mode: MANUAL`): el emisor aprobó y reservó la plata, y tú decides cuándo capturarla. Con captura automática el cobro te llega como `succeeded` desde la autorización: despacha con eso; la captura la hace el procesador después y no te genera ningún aviso.	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 cobro fue rechazado, por el banco emisor o por la evaluación de riesgo. La plata nunca se movió.	Sí
`cancelled`	Se anuló antes de capturar. Se liberó la reserva.	Sí
`refunded`	Se devolvió toda la plata al comprador. Una devolución parcial deja el cobro en `succeeded` y suma `refunded_amount`.	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.

La evaluación de riesgo

Cada cobro con tarjeta pasa por una evaluación de riesgo antes de llegar al banco. Mira el monto, la tarjeta, el banco y el país que la emitieron y los datos del comprador que mandaste, y decide una de tres cosas: dejarlo seguir, rechazarlo —el cobro queda failed sin haber llegado al banco— o retenerlo para revisión, y entonces sigue sin resolverse hasta que se decida.

Corre sola en todos los cobros con tarjeta y no hay nada que prender. Tampoco hay nada que configurar: no puedes cargar reglas propias, listas de bloqueo ni límites. Lo que sí decides tú es la autenticación: con checkout_options.require_3ds en una sesión de checkout el comprador siempre pasa por 3-D Secure. Y mientras más datos del comprador mandes en customer, mejor decide la evaluación.

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://api.lane.money/v1/payments/9b41d0c7-…?sync=true" \
  -H "Authorization: Bearer sk_test_…"

Respuesta 200

{
  "object": "payment",
  "id": "9b41d0c7-…",
  "amount": 11900000,
  "currency": "COP",
  "refunded_amount": 0,
  "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