# Avisos de plataforma

> Los webhooks que recibe una plataforma en Lane: merchant.connected, merchant.approved, merchant.rejected, los avisos de cada cobro y de sus contracargos, qué trae cada uno y en qué orden llegan.

Te enteras por webhook de dos cosas: lo que pasa con tus comercios y cómo termina cada cobro que creaste.

Los avisos llegan a los endpoints de webhook de **tu** empresa, los que registras en **Desarrolladores → Webhooks**. Van firmados como cualquier otro: la verificación y los reintentos están en [Webhooks](https://lane.money/docs/webhooks). El comercio recibe sus propios avisos en sus propios endpoints, aparte.

## Los eventos

| Evento | Cuándo | A qué endpoints llega |
| --- | --- | --- |
| `merchant.connected` | Un comercio quedó conectado contigo. Trae su `reference`. | A todos, de prueba y reales. |
| `merchant.disconnected` | Dejó de estarlo. | A todos. |
| `merchant.approved` | El comercio ya puede cobrar de verdad: desde ese momento tu llave real crea cobros a su nombre. | A todos. |
| `merchant.rejected` | La revisión para cobros reales no pasó. Sigue pudiendo cobrar en modo de prueba. | A todos. |
| `payment.*` | Cambió de estado un cobro que tú creaste. | Solo a los del modo del cobro. |
| `dispute.created`, `dispute.updated` | Un contracargo sobre un cobro que tú creaste. | Solo a los del modo del cobro. |

Todo aviso de un comercio conectado trae `connected_merchant_id` al lado de `id`, `type`, `created` y `data`. Los de un cobro traen además `environment` (`test` o `live`).

## Los avisos de un comercio

**merchant.connected**
```json
{
  "id": "0d5f7a52-…",
  "type": "merchant.connected",
  "created": "2026-10-10T15:02:11.000Z",
  "connected_merchant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "data": {
    "merchant": {
      "object": "connected_merchant",
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Tienda de Ana",
      "reference": "vendedor-77",
      "status": "active",
      "connected_at": "2026-10-10T15:02:11.000Z",
      "disconnected_at": null
    }
  }
}
```

`merchant.disconnected`, `merchant.approved` y `merchant.rejected` traen el mismo objeto. Con `reference` sabes de cuál de tus vendedores se trata sin guardar una tabla de equivalencias.

- **`merchant.approved` y `merchant.rejected` se dicen una vez,** el día en que termina la revisión.
- **`merchant.rejected` no trae el motivo.** Escríbenos para saber qué faltó.
- **No hay un aviso de «activado en pruebas»:** un comercio queda conectado en el mismo momento en que se activa, y eso lo dice `merchant.connected`.

## Los avisos de un cobro

**payment.succeeded, como lo recibe una plataforma**
```json
{
  "id": "3f6c2b1a-…",
  "type": "payment.succeeded",
  "created": "2026-10-10T15:04:05.000Z",
  "environment": "test",
  "connected_merchant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "data": {
    "payment": {
      "id": "a02e5b19-…",
      "amount": 13500000,
      "currency": "COP",
      "status": "succeeded",
      "checkout_session_id": "c1f4a2de-…",
      "extra_items": [
        { "id": "sku-medias", "name": "Medias", "unit_amount": 1500000 }
      ]
    }
  }
}
```

- **Reconoces el pedido por `checkout_session_id`:** es el `id` que te devolvió la API al crear el cobro.
- **`amount` es lo que se cobró,** con los extras incluidos.
- **`extra_items` solo viene cuando el comprador sumó alguno:** es lo que tienes que entregar además del pedido.
- **No trae los datos del comprador, ni los identificadores de su tarjeta, ni tu `metadata`.**

### En qué orden llegan

| El comprador paga con | Primer aviso | Después |
| --- | --- | --- |
| PSE, Nequi, Daviplata o Bre-B | `payment.succeeded`, cuando la red aprueba. | Nada más: no se devuelven ni se anulan. |
| Tarjeta | `payment.succeeded`, cuando el banco aprueba. La captura la hace el procesador después y no te genera otro aviso. | Solo si la autorización se anula antes de capturarse: `payment.cancelled`. |
| Cualquiera, y lo rechazan | `payment.failed` | El comprador puede intentar otra vez en la misma página, con ese medio o con otro. |

> **Cuidado: Con tarjeta, despacha con `payment.succeeded`.** Un cobro con tarjeta se autoriza en el momento y se captura después, del lado del procesador; con la captura automática de estos cobros, para ti es cobrado desde que el banco aprueba, igual que en cualquier pasarela. La captura no te genera un aviso nuevo. Lo único que puede pasar entre una y otra es que la autorización se anule, y ahí recibes `payment.cancelled`. Tu comisión se anota cuando la plata se mueve, en la captura: la ves en tu panel un poco después del aviso.

| Evento | Qué significa |
| --- | --- |
| `payment.authorized` | Solo si pediste captura manual. Con la captura automática de los cobros de la página de Lane no lo vas a ver: te llega `payment.succeeded` directo. |
| `payment.succeeded` | El cobro quedó pagado. |
| `payment.failed` | Lo rechazó el banco, la red o la evaluación de riesgo. No se movió plata. |
| `payment.cancelled` | Se anuló antes de capturarse. |
| `payment.refunded` | El comercio devolvió la plata. |
| `payment.partially_refunded` | El comercio devolvió una parte. Trae `refunded_amount`. |

## Los avisos de un contracargo

`dispute.created` llega cuando un comprador desconoce ante su banco un cobro que tú creaste, y `dispute.updated` cada vez que el caso avanza. Al contracargo responde el comercio, desde su panel. A ti te sirve para saber que tu parte de ese cobro queda retenida mientras el caso esté abierto (ver [Lo que ganas](https://lane.money/docs/plataformas/ganancias)).

## Cómo tratarlos

- **Verifica la firma** con el secreto del endpoint antes de creerle al aviso.
- **Responde `200` de inmediato** y procesa después.
- **El mismo aviso puede llegar dos veces.** Usa su `id` para no entregar un pedido dos veces.
- **Registra un endpoint en cada modo.** Los avisos de un cobro de prueba solo llegan a tus endpoints de prueba, y los de uno real a los reales.
- **Un aviso sale poco después del hecho, no en el mismo instante:** las entregas se despachan cada minuto.
- **Sigues oyendo los cobros que creaste** aunque el comercio se desconecte después.
- **Con la plataforma en pausa no recibes avisos.**

Si dudas de un aviso, o no te llegó, consulta el pago con `GET /v1/payments/{id}` y la cabecera `Lane-On-Behalf-Of`.