Referencia de Eventos
Catálogo completo de eventos webhook que Zertiban emite en cada cambio de estado relevante.
Los eventos webhook son el mecanismo principal de sincronización en tiempo real entre Zertiban y los sistemas integrados del cliente. Cada cambio relevante en el ciclo de vida de un flujo, una operación o un pago PSD2 genera automáticamente un evento webhook firmado, permitiendo que los sistemas externos reaccionen inmediatamente sin necesidad de hacer polling sobre la API.
La recepción de webhooks debe habilitarse previamente con Zertiban. Durante el proceso de integración el cliente deberá indicar:
- El endpoint HTTPS receptor.
- El entorno: Sandbox o Production.
- Los tipos de eventos webhook que desea recibir.
Una vez configurado, Zertiban enviará notificaciones en tiempo real cada vez que se produzca un cambio relevante de estado.
Modelo funcional de eventos
El sistema de eventos de Zertiban se organiza en tres niveles funcionales, cada uno cubriendo una capa distinta del proceso transaccional:
| Nivel | Representa |
|---|---|
FLOW_* | Estado agregado del conjunto completo de operaciones |
OPERATION_* | Acciones individuales ejecutadas por el usuario |
PSD2_PAYMENT_* | Estado bancario real del pago PSD2 |
Eventos de flujo
Los eventos FLOW_* representan el estado agregado del conjunto completo de operaciones asociadas a un flujo.
En la mayoría de integraciones actuales un flujo contiene una única operación, por lo que los eventos de flujo normalmente reflejan directamente el resultado de dicha operación. Sin embargo, la arquitectura de Zertiban está preparada para soportar múltiples operaciones dentro de un mismo flujo.
| Evento | Cuándo se genera |
|---|---|
| FLOW_IN_PROGRESS | Al menos una operación del flujo ha sido abierta |
| FLOW_COMPLETED | Todas las operaciones del flujo han finalizado correctamente |
| FLOW_REJECTED | Todas las operaciones han sido rechazadas |
| FLOW_EXPIRED | Todas las operaciones han expirado |
| FLOW_CANCELLED | El flujo ha sido cancelado |
Eventos de operación
Los eventos OPERATION_* reflejan el estado funcional de una operación individual ejecutada por el usuario final. Permiten monitorizar el comportamiento concreto del pagador dentro del flujo y reaccionar en tiempo real ante cambios funcionales del proceso.
| Evento | Cuándo se genera | Acción sugerida |
|---|---|---|
| OPERATION_OPENED | El pagador abre la URL de la operación | Registrar apertura o inicio de interacción |
| OPERATION_COMPLETED | La operación finaliza correctamente | Marcar factura o cobro como completado |
| OPERATION_REJECTED | El usuario o el banco rechazan la operación | Notificar al equipo de cobros |
| OPERATION_EXPIRED | La operación alcanza su fecha de expiración | Marcar como vencida |
| OPERATION_CANCELLED | La operación es cancelada vía API o Dashboard | Actualizar estado interno |
Eventos de pago PSD2
Los eventos PSD2_PAYMENT_* representan el estado bancario real de un pago PSD2 procesado por Zertiban. A diferencia de los eventos funcionales de flujo u operación, estos eventos reflejan directamente la evolución bancaria del pago dentro de la infraestructura PSD2 y permiten sincronizar estados financieros reales con ERPs, sistemas de conciliación o motores de tesorería.
Se generan automáticamente a medida que el pago avanza dentro del ecosistema bancario y proporcionan visibilidad completa sobre el estado financiero real de la transacción.
| Evento | Cuándo se genera | Acción sugerida |
|---|---|---|
| PSD2_PAYMENT_STATUS_PENDING | El pago ha sido iniciado y se encuentra pendiente | Registrar pago en proceso |
| PSD2_PAYMENT_STATUS_AUTHORIZED | El banco ha autorizado correctamente el pago | Confirmar autorización bancaria |
| PSD2_PAYMENT_STATUS_SETTLED | El pago ha sido liquidado correctamente | Conciliar y cerrar cobro |
| PSD2_PAYMENT_STATUS_PENDING_SETTLED | El pago está pendiente de liquidación final | Mantener seguimiento financiero |
| PSD2_PAYMENT_STATUS_REJECTED | El pago ha sido rechazado | Gestionar incidencia o reintento |
Reglas de emisión e idempotencia
Los eventos PSD2 siguen reglas específicas para evitar duplicados y garantizar consistencia funcional.
Deduplicación de eventos. Antes de emitir un webhook PSD2, Zertiban verifica que no exista previamente un evento enviado para el mismo pago y el mismo estado PSD2 asociado. Esto garantiza idempotencia de envío y evita duplicados funcionales.
Restricción especial para pagos rechazados. El evento PSD2_PAYMENT_STATUS_REJECTED únicamente se emitirá si previamente el pago ha alcanzado un estado transaccional previo válido dentro de su ciclo de vida. Esto asegura coherencia en la secuencia funcional de estados financieros.
¿Qué contiene resource en cada evento?
El contenido del recurso depende del tipo de evento recibido:
| Tipo de evento | Contenido |
|---|---|
FLOW_* | Información agregada del flujo |
OPERATION_* | Información de la operación |
PSD2_PAYMENT_* | Información del pago PSD2 |
Recomendaciones funcionales
Usa eventos PSD2 para conciliación bancaria
Los eventos PSD2_PAYMENT_* representan el estado financiero real del pago y son la mejor fuente para conciliación bancaria, actualización de ERP, tesorería y automatización financiera.
Usa OPERATION_COMPLETED para UX y negocio
El evento OPERATION_COMPLETED representa la finalización funcional de la experiencia del usuario y suele utilizarse para liberar pedidos, marcar facturas, mostrar confirmaciones o avanzar procesos de negocio.
Consumidores webhook idempotentes
Todos los consumidores webhook deben diseñarse para tolerar reintentos, eventos duplicados y reordenamiento temporal de entrega. Se recomienda persistir eventUuid y aplicar procesamiento idempotente, ver Entrega y Reintentos.
Procesamiento asíncrono recomendado
El endpoint webhook debe validar la firma, persistir el evento, responder 200 OK y procesar en background. Esto mejora la resiliencia y evita reintentos innecesarios.