Webhooks (Nequi)

Nequi notifica los cambios de estado a nuestro gateway. Nosotros recibimos, persistimos, actualizamos la transacción y el balance, y enviamos el evento a tu webhookUrl configurada, con reintentos. Puedes configurar una URL distinta por proveedor (NEQUI / BREB) o una única URL para toda la región CO.

Eventos

El nombre del evento llega en el header X-Webhook-Event (no dentro del body).

Evento	Cuándo
`payin.completed`	El cobro (push o QR) fue aprobado y liquidado
`payin.failed`	El cobro fue rechazado o falló
`payin.expired`	El cobro venció sin pago
`payout.completed`	La dispersión se completó
`payout.failed`	La dispersión falló
`payout.expired`	La dispersión venció sin confirmación del proveedor

Payload

payin.completed / payin.failed / payout.completed / payout.failed:

{
  "txId": "3f9f0c2a8b414f0e9a1d2c3b4a5e6f70",
  "type": "PAYIN",
  "status": "COMPLETED",
  "amount": 50000,
  "currency": "COP",
  "feeCharged": 1500,
  "netAmount": 48500,
  "updatedAt": "2026-06-01T10:05:00.000Z"
}

Campo	Descripción
`txId`	ID de la transacción (coincide con el de la creación)
`type`	`PAYIN` o `PAYOUT`
`status`	`COMPLETED` o `FAILED`
`amount`	Monto en pesos COP
`feeCharged`	Fee cobrado en pesos COP (`0` si falló)
`netAmount`	Monto neto acreditado — solo en `payin.completed`

payin.expired / payout.expired:

{
  "txId": "9c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
  "type": "PAYIN",
  "status": "FAILED",
  "amount": 50000,
  "currency": "COP",
  "failureReason": "Cobro Nequi expirado sin pago",
  "expiredAt": "2026-06-01T10:10:00.000Z"
}

Sandbox

En modo sandbox el gateway simula el desenlace automáticamente: al crear una transacción, esta pasa a COMPLETED y recibes el webhook de inmediato con un campo extra:

{ "txId": "...", "type": "PAYIN", "status": "COMPLETED", "amount": 50000, "currency": "COP", "feeCharged": 1500, "netAmount": 48500, "sandbox": true }