Lane · Documentación

Referencia

Cobros

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

Cuerpo

CampoTipoObligatorioDescripción
amountenterosíEn centavos. Cero solo con intent: "account-status".
currencytextonoPor defecto COP.
instrument_idUUIDcondicionalLa tarjeta guardada en Lane. Obligatorio si no mandas provider_instrument_id; no mandes los dos.
provider_instrument_idtextocondicionalEl identificador de la tarjeta en el procesador, para migraciones.
initiatorcustomer · merchantnoQuién dispara el cobro. Por defecto merchant.
cvvtextocondicional3 o 4 dígitos. Obligatorio con initiator: "customer", prohibido con merchant.
order_typetextonoEl tipo de orden para la red. Ver Cobro recurrente.
intentauthorization · pre-authorization · account-statusnoPor defecto authorization.
captureobjetono{ "mode": "AUTOMATIC" | "MANUAL" | "SCHEDULED" }. Manual deja el cobro en authorized.
installmentsobjetono{ "quantity": 3 }, mínimo 2. Omítelo para un pago sin cuotas.
parent_transaction_dataobjetocondicionalEnlace al primer cobro de la serie. Obligatorio en cobros recurrentes sin el cliente presente.
metadataobjetonoVuelve intacto en el cobro y en el webhook.

Cobrar una tarjeta guardada

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

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

CampoTipoObligatorioDescripción
syncbooleanonotrue consulta al procesador antes de responder. Más lento; para depurar.

Consultar

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

Respuesta 200

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

CampoTipoObligatorioDescripción
statustextonoUno o varios separados por coma: succeeded,refunded.
customer_idUUIDnoSolo los de ese cliente.
created_afterfechanoISO 8601. Desde esa fecha en adelante.
limitenteronoPor defecto 25, máximo 100.
starting_aftercursornoEl next_cursor de la página anterior.

Cobros aprobados de esta semana

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

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

RutaRequiereDeja el cobro en
POST /v1/payments/{id}/captureauthorizedsucceeded
POST /v1/payments/{id}/cancelauthorizedcancelled
POST /v1/payments/{id}/adjustauthorizedauthorized, con otro monto
POST /v1/payments/{id}/refundsucceededrefunded
POST /v1/payments/{id}/cancel-or-refundauthorized o succeededSegún cuál fuera

Reembolso parcial

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 }'
Solo la tarjeta se devuelve. Un cobro por PSE, Nequi, Daviplata o Bre-B no admite refund ni cancel. Ver Medios instantáneos.

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