Para plataformas

Avisos de plataforma

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

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

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

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

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.

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