Para plataformas

Cobrar a nombre de tus comercios

Tu plataforma trae los comercios. Cada uno tiene su propia cuenta en Lane, y tú creas los cobros a su nombre con una sola llave: la tuya.

Una plataforma es una empresa que vende a través de otros: un bot que toma pedidos por chat, un sistema de reservas, un catálogo compartido. En Lane cada comercio que traes es una empresa aparte, con su panel, su verificación y su cuenta bancaria. La plata de cada venta es del comercio; tu plataforma crea el cobro, se entera de cómo termina y gana su parte.

Ser plataforma se habilita. No es una opción del panel. Crea la cuenta de tu empresa en lane.money/auth/signup?como=plataforma (sirve para una empresa de cualquier país: no necesitas un comercio en Colombia) y escríbenos: el equipo de Lane la marca como plataforma y deja acordadas tus condiciones, lo que pagan tus comercios por cobro y tu parte. Hasta entonces, las rutas de estas guías responden 403 con code: not_a_platform.

El recorrido completo

Creas la cuenta de tu empresa y Lane habilita tu plataforma con tus condiciones.
Invitas a un comercio con un enlace de registro. El comercio crea su cuenta, acepta la conexión y activa su comercio.
Te llega `merchant.connected` con el id del comercio. Desde ese momento puedes cobrar a su nombre en modo de prueba.
Creas un cobro con tu llave y la cabecera Lane-On-Behalf-Of. Recibes la dirección de una página de pago y se la mandas al comprador.
El comprador paga en esa página, con tarjeta, PSE, Nequi, Daviplata o Bre-B.
Te llega el aviso del cobro en tu webhook, y entregas el pedido.
Lane revisa al comercio para cobros reales. Cuando lo aprueba te llega merchant.approved y tu llave real ya cobra a su nombre.
Una vez al mes Lane te paga tu parte de los cobros que creó tu plataforma.

Los caminos que tienes

Para traer un comercio

Camino	Cuándo sirve	Cómo
Enlace desde tu panel	Traes pocos comercios, o alguien de tu equipo los invita a mano.	En Plataforma, crea el enlace y cópialo.
Enlace por API	Tu sistema registra vendedores y quieres invitarlos sin que nadie intervenga.	`POST /v1/platform/signup-links`
Enlace atado a un correo	Quieres estar seguro de quién lo usa.	Manda `email`: solo una cuenta con ese correo puede aceptarlo.
Enlace con tu referencia	Necesitas saber cuál de tus vendedores quedó como qué comercio.	Manda `reference`: vuelve en `merchant.connected` y en la lista de tus comercios.
Un comercio que ya está en Lane	El vendedor ya tiene cuenta y comercio activo.	El mismo enlace: entra con su cuenta y queda conectado al aceptar.

El detalle está en Traer comercios.

Para cobrar

Camino	Cuándo sirve	Qué mandas
Solo un total	El comprador ya sabe qué pidió.	`amount`
Con los productos del pedido	Quieres que el comprador reconozca lo que va a pagar.	`amount` y `line_items`
Con productos extra	Quieres ofrecer hasta tres productos más antes de pagar.	`extra_items`
Con todos los medios	Dejas que el comprador elija cómo pagar.	Nada: es lo que pasa por defecto.
Con algunos medios	No quieres ofrecer alguno (por ejemplo, solo transferencias).	`available_payment_methods`
Con un solo medio	El comprador ya eligió en tu chat o en tu app.	`payment_method`
Con vuelta a tu sitio	Tienes una página a la que el comprador debe regresar.	`success_url` y `cancel_url`
Que dure más o menos	Un cobro que se paga hoy, o una cotización que vale un mes.	`expires_in`

Todos son el mismo POST /v1/checkout/sessions, y se combinan. Están en Crear cobros.

Para enterarte

Camino	Cuándo sirve	Cómo
Avisos por webhook	Siempre. Es la forma de saber que un cobro se pagó.	Un endpoint en Desarrolladores → Webhooks de tu empresa.
Consultar un pago	Para depurar, o para confirmar un aviso que no te llegó.	`GET /v1/payments/{id}` con `Lane-On-Behalf-Of`.
Consultar tus comercios	Para saber quién está conectado y quién puede cobrar ya.	`GET /v1/platform/merchants`
Tu panel	Para ver lo que ganaste cada mes y por cuál comercio entró.	Plataforma, en el panel de tu empresa.

Los eventos y su contenido están en Avisos de plataforma.

Las guías

Traer comercios: El enlace de registro, lo que hace el comercio con él, sus documentos y el paso a cobros reales.
Crear cobros: La cabecera, el cuerpo, los medios de pago, los productos extra y cada error.
Avisos de plataforma: Qué eventos recibes, qué trae cada uno y cuál llega primero cuando se paga con tarjeta.
Lo que ganas: Cómo se calcula tu parte, cuándo queda lista para pagar y dónde la ves.
Probar tu integración: El recorrido completo en modo de prueba, y la lista para salir a cobros reales.

Lo que una plataforma ve y lo que no

Ve los comercios conectados con ella, los cobros que ella creó y cómo terminó cada uno.
No ve los cobros que el comercio hace por su cuenta, ni sus clientes, ni sus llaves.
No recibe los datos del comprador (nombre, correo, documento) ni los identificadores de su tarjeta, ni en los avisos ni al consultar un pago. Esos datos son del comercio.
No toca la plata. Cada venta llega a la cuenta del comercio.

Límites

300 peticiones por minuto por llave. Pasarse responde 429 con code: rate_limited y la cabecera Retry-After.
Tres rutas admiten actuar a nombre de un comercio: crear un cobro (POST /v1/checkout/sessions o su alias POST /v1/payment_links) y consultar un pago (GET /v1/payments/{id}). Las demás responden 403 con code: on_behalf_not_supported.
Un comercio está bajo una sola plataforma a la vez.

Lo que todavía no hace

No se crea un comercio por API: cada uno se registra con su enlace.
No se reembolsa ni se anula un cobro con la llave de la plataforma: lo hace el comercio, desde su panel o con su llave.
El estado de cuenta de tu parte no está en la API: se ve en tu panel.
Un comercio conectado no se desconecta desde su panel: lo hace el equipo de Lane.
Los productos extra se ofrecen antes de pagar, no después.

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