Webhooks
Descripción
Esta sección centraliza todo lo que necesitas para configurar y probar el flujo completo de webhooks en la plataforma de Pagos-como-Servicio (PaaS) de Passport. Desde la creación de la suscripción hasta la validación end-to-end (E2E) de pagos salientes y entrantes.
Configuración de Webhook en el Tablero de Control
Antes de recibir notificaciones, debes registrar tu Webhook en el Tablero de Control de Passport. A continuación detallo cada campo de la pantalla de “Crear Webhook”:
El administrador de la Fintech debe:
- Ingresar al Tablero de Control de Passport.
- Acceder a Plataforma > Webhooks
- Seleccionar Crear Webhook +
- Configurar el Webhook
- Hacer click en Guardar
Crear Webhook
Configuración de Webhooks
Detalles de los Parámetros de Configuración
| Campos | Descripción |
|---|---|
| URL Callback | Dirección HTTPS a la que Passport enviará las notificaciones. Debe ser accesible públicamente. |
| Token de Segredo | Clave que usarás para calcular/verificar la firma HMAC-SHA256. ¡Guárdala en secreto! |
| Modo de Entrega | Mecanismo de retry que quieras usar (“Una Vez" o “Reintentar”). |
| Webhook Activado | Selector SI/NO para habilitar o deshabilitar las notificaciones. |
| Eventos | Tipo de Eventos: Confirmado, Entrante, Liquidado, Rechazado. |
Comportamiento de 'Reintento' en los Webhooks
Cuando el Modo de Entrega está configurado como 'Reintentar' tras un fallo del webhook, la plataforma intentará reenviarlos hasta 12 veces. El primer intento se realiza 1 segundo después del evento de fallo, es decir:
- 1_2*_0 = 1s para el primer reintento.
- 1_2*_1 = 2s para el segundo.
- 1_2*_2 = 4s para el tercero.
- 1_2*_3 = 8s para el cuarto.
Selección de Eventos
Bajo el título Eventos elige la categoría Pagos y marca uno o varios (el nombre del evento en la notificación está en paréntesis):
Inbound (Pago Entrante) (
payment.inbound.received)- El pago fue enviado exitosamente hacia ti dentro de la red Bre-B. Es decir, estás recibiendo un pago (tú o el cliente que administras).
Confirmed (Pago Confirmado) (
payment.inbound.confirmedopayment.outbound.confirmed)- El pago entrante o saliente fue confirmado por el banco originador o receptor.
Settled (Pago Liquidado) (
payment.inbound.settledopayment.outbound.settled)- El pago fue completado en el banco originador o receptor.
Rejected (
payment.inbound.rejectedopayment.outbound.rejected)- El pago fue rechazado. Revisa el cuerpo de la respuesta para más detalles.
Flujo de Eventos (Inbound - Entrante)
Para transacciones entrantes (hacia tu cuenta o las de tus clientes), el flujo simple es:
payment.inbound.received → payment.inbound.confirmed → payment.inbound.settled
Flujo de Eventos (Outbound - Saliente)
Para transacciones salientes (desde tu cuenta o las de tus clientes), los eventos principales son:
payment.outbound.confirmed → payment.outbound.settled
Rechazo de Pagos
Si las validaciones en el MOL resultan en que un pago se clasifique como Rejected, esto puede ocurrir en cualquier etapa del proceso. El webhook entregará el código de estado y una descripción detallada del error detectado.
payment.inbound.rejectedpayment.outbound.rejected
"error" : { "code": "B101", "description": "Account not found",}Ejemplos de Eventos
Pago Entrante (Inbound)
El evento payment.inbound.settled ocurre cuando una transacción se acredita exitosamente en tu cuenta o en la cuenta de tu cliente. Puede originarse por una transacción Llave-a-Llave o por código QR.
Análogamente, payment.outbound.settled indica que tu transacción se liquidó en el banco receptor.
{ "payment_id": "7f2be799-9bad-4e87-8fd1-204b67c8e3c1", "reference": "20250919890505363VIS110763168961353", "account_id": "f49ba409-8f89-4d9a-9687-c5e7e5bb3ba6", "customer_id": "56334512-ead6-4b33-90fa-6b7c69052f4e", "amount": { "value": "100000.00", "currency": "COP" }, "created_at": "2025-09-19 16:18:38.860160+00:00", "updated_at": "2025-09-19 16:18:39.821841+00:00", "status": "SETTLED", "Event": "payment.inbound.rexeived"}Pago Confirmado (Confirmed)
El evento payment.inbound.confirmed señala la confirmación emitida por el Participante (banco receptor) sobre la transacción. Esta confirmación sucede si se cumplen condiciones como la validez de la llave y su asociación a una cuenta existente en el banco receptor (entre otras).
Tras el evento inbound inicial, payment.inbound.confirmed indica un curso exitoso. Si surge algún problema a nivel de Nodo, MOL o Banco, el siguiente evento será payment.inbound.rejected.
Si la dirección es saliente, verás payment.outbound.confirmed o payment.outbound.rejected en caso de inconsistencia.
{ "payment_id": "7f2be799-9bad-4e87-8fd1-204b67c8e3c1", "reference": "20250919890505363VIS110763168961353", "account_id": "f49ba409-8f89-4d9a-9687-c5e7e5bb3ba6", "customer_id": "56334512-ead6-4b33-90fa-6b7c69052f4e", "amount": { "value": "100000.00", "currency": "COP" }, "created_at": "2025-09-19 16:18:38.860160+00:00", "updated_at": "2025-09-19 16:18:40.460027+00:00", "status": "CONFIRMED", "Event": "payment.inbound.confirmed"Pago Liquidado (Settled)
Uno de los eventos más relevantes: payment.inbound.settled o payment.outbound.settled marca la transferencia exitosa de fondoshacia/desde la cuenta del cliente. En otras palabras, el cliente completó el pago por el producto o servicio y los fondos ya están disponibles en la cuenta.
Para outbound, se refiere al movimiento de fondos desde una cuenta hacia la cuenta de destino.
{ "payment_id": "7f2be799-9bad-4e87-8fd1-204b67c8e3c1", "reference": "Dispersion a merchant PEPITO", "account_id": "f49ba409-8f89-4d9a-9687-c5e7e5bb3ba6", "customer_id": "56334512-ead6-4b33-90fa-6b7c69052f4e", "amount": { "value": "100000.00", "currency": "COP" }, "created_at": "2025-09-22 15:14:38.790966+00:00", "updated_at": "2025-09-22 15:15:21.388715+00:00", "status": "SETTLED", "breb_recipient_id": "0f7d4398-5fbd-4889-93ed-37e4ee20534d", "Event": "payment.inbound.settled"}La dirección del pago aparecerá reflejada en los eventos:
payment.inbound.rejectedpara pagos entrantes rechazados.payment.outbound.rejectedpara pagos salientes rechazados.