# Cobrar a nombre de tus comercios

> Guía para plataformas en Lane: los caminos para traer comercios, crear cobros a su nombre con tu propia llave, enterarte de cómo termina cada uno y recibir tu parte.

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.

> **Nota: Ser plataforma se habilita.** No es una opción del panel. Crea la cuenta de tu empresa en [lane.money/auth/signup?como=plataforma](https://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

1. **Creas la cuenta de tu empresa** y **Lane habilita tu plataforma** con tus condiciones.
2. **Invitas a un comercio** con un enlace de registro. El comercio crea su cuenta, acepta la conexión y activa su comercio.
3. **Te llega `merchant.connected`** con el `id` del comercio. Desde ese momento puedes cobrar a su nombre en modo de prueba.
4. **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.
5. **El comprador paga** en esa página, con tarjeta, PSE, Nequi, Daviplata o Bre-B.
6. **Te llega el aviso** del cobro en tu webhook, y entregas el pedido.
7. **Lane revisa al comercio para cobros reales.** Cuando lo aprueba te llega `merchant.approved` y tu llave real ya cobra a su nombre.
8. **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](https://lane.money/docs/plataformas/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](https://lane.money/docs/plataformas/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](https://lane.money/docs/plataformas/avisos).

## Las guías

- [Traer comercios](https://lane.money/docs/plataformas/comercios): El enlace de registro, lo que hace el comercio con él, sus documentos y el paso a cobros reales.
- [Crear cobros](https://lane.money/docs/plataformas/cobros): La cabecera, el cuerpo, los medios de pago, los productos extra y cada error.
- [Avisos de plataforma](https://lane.money/docs/plataformas/avisos): Qué eventos recibes, qué trae cada uno y cuál llega primero cuando se paga con tarjeta.
- [Lo que ganas](https://lane.money/docs/plataformas/ganancias): Cómo se calcula tu parte, cuándo queda lista para pagar y dónde la ves.
- [Probar tu integración](https://lane.money/docs/plataformas/pruebas): 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.