Lane · Documentación

Para plataformas

Crear cobros a nombre de un comercio

Usas tu propia llave y dices a nombre de quién actúas. El cobro es del comercio; queda marcado como hecho por tu plataforma.

La plata llega a la cuenta del comercio y el cobro aparece en su panel. La marca de que lo creó tu plataforma es lo que hace que recibas sus avisos y que cuente para tu parte.

POST/v1/checkout/sessions

Crea el cobro y devuelve la dirección de la página de pago. Responde 201.

Cabeceras

Cuerpo

Crear el cobro de un pedido

curl -X POST https://api.lane.money/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_…" \
  -H "Lane-On-Behalf-Of: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Idempotency-Key: pedido-4821" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12000000,
    "description": "Pedido 4821",
    "line_items": [
      { "name": "Camiseta negra", "quantity": 2, "unit_amount": 5000000 },
      { "name": "Envío", "quantity": 1, "unit_amount": 2000000 }
    ],
    "extra_items": [
      { "id": "sku-medias", "name": "Medias", "unit_amount": 1500000, "compare_at_amount": 2000000 }
    ],
    "customer": { "name": "Ana Pérez", "email": "ana@ejemplo.com" }
  }'

// En tu servidor, cuando tu bot cierra un pedido.
async function crearCobro(pedido) {
  const respuesta = await fetch("https://api.lane.money/v1/checkout/sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LANE_SECRET_KEY}`,
      "Lane-On-Behalf-Of": pedido.comercioLaneId,
      // La misma clave en cada reintento del mismo pedido.
      "Idempotency-Key": `pedido-${pedido.id}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: pedido.totalCentavos,
      description: `Pedido ${pedido.numero}`,
      line_items: pedido.productos,
    }),
  });

  const cobro = await respuesta.json();
  if (!respuesta.ok) throw new Error(`${cobro.code}: ${cobro.error}`);

  // Con este id reconoces el pedido cuando llegue el aviso.
  await pedido.guardarSesion(cobro.id);
  return cobro.checkout_url;
}

Respuesta

{
  "object": "checkout.session",
  "id": "c1f4a2de-…",
  "environment": "test",
  "amount": 12000000,
  "currency": "COP",
  "status": "created",
  "checkout_url": "https://lane.money/pay/c1f4a2de-…",
  "payment": null
}

Guarda id: es con lo que reconoces el pedido cuando llegue el aviso (checkout_session_id). payment llega en null porque el pago se crea cuando el comprador elige cómo pagar.

Los medios de pago

La página ofrece un medio cuando se cumplen tres cosas:

1. Lo pediste, o no pediste ninguno (y entonces entran todos).
2. El comercio lo tiene habilitado en el modo de tu llave.
3. El medio admite el monto. Los topes de cada red están en Medios instantáneos.

Los medios instantáneos (PSE, Nequi, Daviplata y Bre-B) no admiten reembolso ni anulación. La tarjeta sí, y la hace el comercio.

Los productos extra

El comprador ve cada extra en el resumen del pedido, con su precio y, si mandaste compare_at_amount, el anterior tachado. Lo suma o lo quita antes de pagar. El precio es el que quedó en el cobro: la página no puede cambiarlo.

El total puede ser mayor que el que mandaste. Si ofreces extra_items, el comprador puede sumarlos y se cobra amount más esos extras. Lee el total y los extras del aviso del pago: no asumas el monto que enviaste. Si con un extra el total ya no cabe en un medio, ese medio deja de ofrecerse.

Lo que ve el comprador

• El pedido, con sus productos y el total en pesos, y los extras para sumar.
• Los medios que el cobro ofrece, para elegir uno. Con un solo medio, la página va directo a él.
• Con tarjeta, escribe los datos de la tarjeta y después su código de seguridad para confirmar.
• Con PSE, va al portal de su banco y vuelve. Con Nequi, aprueba en su app. Con Daviplata, escribe el código que le llega por SMS. Con Bre-B, escanea un código o usa su llave.
• Si un intento falla, puede intentar con otro medio en la misma página.
• Cuando paga, ve la confirmación y, si mandaste success_url, vuelve ahí.

La página lleva el logo y los colores que el comercio configuró en su panel, en Tu checkout. Si no configuró nada, sale con la marca de Lane.

Errores

Forma de un error

{
  "error": "Este comercio todavía no puede cobrar con ese medio de pago",
  "code": "payment_method_unavailable",
  "details": "Los que tiene habilitados son: card, pse.",
  "request_id": "b7d1c6f0-…"
}

Consultar un pago

GET/v1/payments/{id}

El pago de un cobro que tú creaste, con la cabecera Lane-On-Behalf-Of.

Solo encuentra los pagos de cobros que creó tu plataforma; uno que el comercio hizo por su cuenta responde 404. Responde sin los datos del comprador y sin los identificadores de su tarjeta. El id del pago lo trae el aviso.

Lo que se ignora en estos cobros

En los cobros que crea una plataforma se ignoran multi_use, max_uses, error_url, style_config y checkout_options: la página es la de Lane, con la marca del comercio.

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