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 cuatro niveles funcionales: tres que cubren capas distintas del proceso transaccional y uno que cubre el ciclo de vida de la organización.

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
BUSINESS_*	Estado de una organización dentro de Zertiban

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_NOT_COMPLETED	El flujo ha terminado sin ninguna operación completada
FLOW_PARTIALLY_COMPLETED	Algunas operaciones se han completado y el resto no
FLOW_EXPIRED	Todas las operaciones han expirado
FLOW_CANCELLED	El flujo ha sido cancelado

FLOW_IN_PROGRESS

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "FLOW_IN_PROGRESS",
  "eventUuid": "ddd6c831-b815-5a12-856f-7b9a331200e7",
  "timestamp": "2026-09-17T09:40:02.115Z",
  "resource": {
    "uuid": "39b71b93-e646-40eb-8d6b-abc728e40851",
    "externalId": "INV-2026-000123",
    "status": "IN_PROGRESS"
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "FLOW_IN_PROGRESS",
  "eventUuid": "ddd6c831-b815-5a12-856f-7b9a331200e7",
  "timestamp": "2026-09-17T09:40:02.115Z",
  "resource": {
    "uuid": "39b71b93-e646-40eb-8d6b-abc728e40851",
    "externalId": "INV-2026-000123",
    "status": "IN_PROGRESS"
  }
}

FLOW_REJECTED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "FLOW_REJECTED",
  "eventUuid": "7cf54949-de85-5a0a-b0eb-c0cad009f78a",
  "timestamp": "2026-09-17T09:46:31.902Z",
  "resource": {
    "uuid": "39b71b93-e646-40eb-8d6b-abc728e40851",
    "externalId": "INV-2026-000123",
    "status": "REJECTED"
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "FLOW_REJECTED",
  "eventUuid": "7cf54949-de85-5a0a-b0eb-c0cad009f78a",
  "timestamp": "2026-09-17T09:46:31.902Z",
  "resource": {
    "uuid": "39b71b93-e646-40eb-8d6b-abc728e40851",
    "externalId": "INV-2026-000123",
    "status": "REJECTED"
  }
}

FLOW_NOT_COMPLETED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "FLOW_NOT_COMPLETED",
  "eventUuid": "f55ba01d-230a-5eda-85ca-6977c3c813d2",
  "timestamp": "2026-09-17T09:52:07.338Z",
  "resource": {
    "uuid": "39b71b93-e646-40eb-8d6b-abc728e40851",
    "externalId": "INV-2026-000123",
    "status": "NOT_COMPLETED"
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "FLOW_NOT_COMPLETED",
  "eventUuid": "f55ba01d-230a-5eda-85ca-6977c3c813d2",
  "timestamp": "2026-09-17T09:52:07.338Z",
  "resource": {
    "uuid": "39b71b93-e646-40eb-8d6b-abc728e40851",
    "externalId": "INV-2026-000123",
    "status": "NOT_COMPLETED"
  }
}

FLOW_PARTIALLY_COMPLETED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "FLOW_PARTIALLY_COMPLETED",
  "eventUuid": "f096c465-a9c2-5c5f-8678-fa0d1216f84c",
  "timestamp": "2026-09-17T09:55:44.061Z",
  "resource": {
    "uuid": "39b71b93-e646-40eb-8d6b-abc728e40851",
    "externalId": "INV-2026-000123",
    "status": "PARTIALLY_COMPLETED"
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "FLOW_PARTIALLY_COMPLETED",
  "eventUuid": "f096c465-a9c2-5c5f-8678-fa0d1216f84c",
  "timestamp": "2026-09-17T09:55:44.061Z",
  "resource": {
    "uuid": "39b71b93-e646-40eb-8d6b-abc728e40851",
    "externalId": "INV-2026-000123",
    "status": "PARTIALLY_COMPLETED"
  }
}

FLOW_COMPLETED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "FLOW_COMPLETED",
  "eventUuid": "e4159bb3-dce9-5105-a1be-07e2272a969f",
  "timestamp": "2026-09-17T09:41:12.482Z",
  "resource": {
    "uuid": "39b71b93-e646-40eb-8d6b-abc728e40851",
    "externalId": "INV-2026-000123",
    "status": "COMPLETED"
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "FLOW_COMPLETED",
  "eventUuid": "e4159bb3-dce9-5105-a1be-07e2272a969f",
  "timestamp": "2026-09-17T09:41:12.482Z",
  "resource": {
    "uuid": "39b71b93-e646-40eb-8d6b-abc728e40851",
    "externalId": "INV-2026-000123",
    "status": "COMPLETED"
  }
}

FLOW_EXPIRED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "FLOW_EXPIRED",
  "eventUuid": "59cb274a-35d9-595b-b6fa-67b3fe5c6b62",
  "timestamp": "2026-09-24T00:00:05.004Z",
  "resource": {
    "uuid": "39b71b93-e646-40eb-8d6b-abc728e40851",
    "externalId": "INV-2026-000123",
    "status": "EXPIRED"
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "FLOW_EXPIRED",
  "eventUuid": "59cb274a-35d9-595b-b6fa-67b3fe5c6b62",
  "timestamp": "2026-09-24T00:00:05.004Z",
  "resource": {
    "uuid": "39b71b93-e646-40eb-8d6b-abc728e40851",
    "externalId": "INV-2026-000123",
    "status": "EXPIRED"
  }
}

FLOW_CANCELLED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "FLOW_CANCELLED",
  "eventUuid": "f29bef98-7975-5919-b609-19f4aa2feecd",
  "timestamp": "2026-09-17T11:20:49.750Z",
  "resource": {
    "uuid": "8c5e3e83-5145-4c57-8d3f-ac5f9c6652f2",
    "externalId": null,
    "status": "CANCELLED"
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "FLOW_CANCELLED",
  "eventUuid": "f29bef98-7975-5919-b609-19f4aa2feecd",
  "timestamp": "2026-09-17T11:20:49.750Z",
  "resource": {
    "uuid": "8c5e3e83-5145-4c57-8d3f-ac5f9c6652f2",
    "externalId": null,
    "status": "CANCELLED"
  }
}

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

OPERATION_OPENED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "OPERATION_OPENED",
  "eventUuid": "fdba93d4-3f32-5fce-8c6b-36736e67f492",
  "timestamp": "2026-09-17T09:40:02.117Z",
  "resource": {
    "uuid": "bd51a1af-7779-4010-a876-0630851a1858",
    "externalId": "OP-2026-000123",
    "status": "OPENED"
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "OPERATION_OPENED",
  "eventUuid": "fdba93d4-3f32-5fce-8c6b-36736e67f492",
  "timestamp": "2026-09-17T09:40:02.117Z",
  "resource": {
    "uuid": "bd51a1af-7779-4010-a876-0630851a1858",
    "externalId": "OP-2026-000123",
    "status": "OPENED"
  }
}

OPERATION_REJECTED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "OPERATION_REJECTED",
  "eventUuid": "40df6070-422c-520f-af35-f1331317b125",
  "timestamp": "2026-09-17T09:46:31.900Z",
  "resource": {
    "uuid": "bd51a1af-7779-4010-a876-0630851a1858",
    "externalId": "OP-2026-000123",
    "status": "REJECTED"
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "OPERATION_REJECTED",
  "eventUuid": "40df6070-422c-520f-af35-f1331317b125",
  "timestamp": "2026-09-17T09:46:31.900Z",
  "resource": {
    "uuid": "bd51a1af-7779-4010-a876-0630851a1858",
    "externalId": "OP-2026-000123",
    "status": "REJECTED"
  }
}

OPERATION_COMPLETED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "OPERATION_COMPLETED",
  "eventUuid": "13e83b92-13d8-5b6d-94c0-05feb58d3189",
  "timestamp": "2026-09-17T09:41:12.480Z",
  "resource": {
    "uuid": "bd51a1af-7779-4010-a876-0630851a1858",
    "externalId": "OP-2026-000123",
    "status": "COMPLETED"
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "OPERATION_COMPLETED",
  "eventUuid": "13e83b92-13d8-5b6d-94c0-05feb58d3189",
  "timestamp": "2026-09-17T09:41:12.480Z",
  "resource": {
    "uuid": "bd51a1af-7779-4010-a876-0630851a1858",
    "externalId": "OP-2026-000123",
    "status": "COMPLETED"
  }
}

OPERATION_EXPIRED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "OPERATION_EXPIRED",
  "eventUuid": "d863ec53-51f6-5434-83d0-96de7e909fb3",
  "timestamp": "2026-09-24T00:00:05.001Z",
  "resource": {
    "uuid": "bd51a1af-7779-4010-a876-0630851a1858",
    "externalId": "OP-2026-000123",
    "status": "EXPIRED"
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "OPERATION_EXPIRED",
  "eventUuid": "d863ec53-51f6-5434-83d0-96de7e909fb3",
  "timestamp": "2026-09-24T00:00:05.001Z",
  "resource": {
    "uuid": "bd51a1af-7779-4010-a876-0630851a1858",
    "externalId": "OP-2026-000123",
    "status": "EXPIRED"
  }
}

OPERATION_CANCELLED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "OPERATION_CANCELLED",
  "eventUuid": "ea318317-8c89-5ffd-8c4d-77cc51bdf3f5",
  "timestamp": "2026-09-17T11:20:49.748Z",
  "resource": {
    "uuid": "bd51a1af-7779-4010-a876-0630851a1858",
    "externalId": "OP-2026-000123",
    "status": "CANCELLED"
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "OPERATION_CANCELLED",
  "eventUuid": "ea318317-8c89-5ffd-8c4d-77cc51bdf3f5",
  "timestamp": "2026-09-17T11:20:49.748Z",
  "resource": {
    "uuid": "bd51a1af-7779-4010-a876-0630851a1858",
    "externalId": "OP-2026-000123",
    "status": "CANCELLED"
  }
}

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.

PSD2_PAYMENT_STATUS_PENDING

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "PSD2_PAYMENT_STATUS_PENDING",
  "eventUuid": "778fb46b-f31f-524c-87da-fc25e8c2f99e",
  "timestamp": "2026-09-17T09:41:05.233Z",
  "resource": {
    "paymentUuid": "14c56ab6-d0f0-4b13-9a9a-d9e722aff880",
    "psd2Payment": {
      "status": {
        "status": "PAYMENT_STATUS_PENDING",
        "code": "PENDING",
        "step": "PAYMENT_STATUS_PENDING"
      }
    }
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "PSD2_PAYMENT_STATUS_PENDING",
  "eventUuid": "778fb46b-f31f-524c-87da-fc25e8c2f99e",
  "timestamp": "2026-09-17T09:41:05.233Z",
  "resource": {
    "paymentUuid": "14c56ab6-d0f0-4b13-9a9a-d9e722aff880",
    "psd2Payment": {
      "status": {
        "status": "PAYMENT_STATUS_PENDING",
        "code": "PENDING",
        "step": "PAYMENT_STATUS_PENDING"
      }
    }
  }
}

PSD2_PAYMENT_STATUS_AUTHORIZED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "PSD2_PAYMENT_STATUS_AUTHORIZED",
  "eventUuid": "0904353e-f46f-550c-99c7-0744ca63f4cf",
  "timestamp": "2026-09-17T09:41:09.871Z",
  "resource": {
    "paymentUuid": "14c56ab6-d0f0-4b13-9a9a-d9e722aff880",
    "psd2Payment": {
      "status": {
        "status": "PAYMENT_DETAILS_VALID_AUTHORIZED",
        "code": "AUTHORIZED",
        "step": "PAYMENT_DETAILS_AUTHORIZED_VALID"
      }
    }
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "PSD2_PAYMENT_STATUS_AUTHORIZED",
  "eventUuid": "0904353e-f46f-550c-99c7-0744ca63f4cf",
  "timestamp": "2026-09-17T09:41:09.871Z",
  "resource": {
    "paymentUuid": "14c56ab6-d0f0-4b13-9a9a-d9e722aff880",
    "psd2Payment": {
      "status": {
        "status": "PAYMENT_DETAILS_VALID_AUTHORIZED",
        "code": "AUTHORIZED",
        "step": "PAYMENT_DETAILS_AUTHORIZED_VALID"
      }
    }
  }
}

Otras variantes de psd2Payment.status. El resto del cuerpo es idéntico.

FAILED

{
  "status": {
    "status": "PAYMENT_DETAILS_AUTHORIZED_FAILED",
    "code": "AUTHORIZED",
    "step": "PAYMENT_DETAILS_AUTHORIZED_FAILED"
  }
}

REJECTED

{
  "status": {
    "status": "PAYMENT_DETAILS_AUTHORIZED_REJECTED",
    "code": "AUTHORIZED",
    "step": "PAYMENT_DETAILS_AUTHORIZED_REJECTED"
  }
}

PSD2_PAYMENT_STATUS_PENDING_SETTLED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "PSD2_PAYMENT_STATUS_PENDING_SETTLED",
  "eventUuid": "85a73fb3-00d0-58f5-8a82-fff1336e30c5",
  "timestamp": "2026-09-17T09:41:10.406Z",
  "resource": {
    "paymentUuid": "14c56ab6-d0f0-4b13-9a9a-d9e722aff880",
    "psd2Payment": {
      "status": {
        "status": "PAYMENT_DETAILS_VALID_PENDING_SETTLED",
        "code": "PENDING_SETTLED",
        "step": "PAYMENT_DETAILS_VALID_PENDING_SETTLED"
      }
    }
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "PSD2_PAYMENT_STATUS_PENDING_SETTLED",
  "eventUuid": "85a73fb3-00d0-58f5-8a82-fff1336e30c5",
  "timestamp": "2026-09-17T09:41:10.406Z",
  "resource": {
    "paymentUuid": "14c56ab6-d0f0-4b13-9a9a-d9e722aff880",
    "psd2Payment": {
      "status": {
        "status": "PAYMENT_DETAILS_VALID_PENDING_SETTLED",
        "code": "PENDING_SETTLED",
        "step": "PAYMENT_DETAILS_VALID_PENDING_SETTLED"
      }
    }
  }
}

Otras variantes de psd2Payment.status. El resto del cuerpo es idéntico.

FAILED

{
  "status": {
    "status": "PAYMENT_DETAILS_PENDING_SETTLED_FAILED",
    "code": "PENDING_SETTLED",
    "step": "PAYMENT_DETAILS_PENDING_SETTLED_FAILED"
  }
}

REJECTED

{
  "status": {
    "status": "PAYMENT_DETAILS_PENDING_SETTLED_REJECTED",
    "code": "PENDING_SETTLED",
    "step": "PAYMENT_DETAILS_PENDING_SETTLED_REJECTED"
  }
}

PSD2_PAYMENT_STATUS_SETTLED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "PSD2_PAYMENT_STATUS_SETTLED",
  "eventUuid": "33936899-3ca5-5345-9c8e-0ce358bed0a3",
  "timestamp": "2026-09-17T14:02:51.640Z",
  "resource": {
    "paymentUuid": "14c56ab6-d0f0-4b13-9a9a-d9e722aff880",
    "psd2Payment": {
      "status": {
        "status": "PAYMENT_DETAILS_VALID_SETTLED",
        "code": "SETTLED",
        "step": "PAYMENT_DETAILS_SETTLED_VALID"
      }
    }
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "PSD2_PAYMENT_STATUS_SETTLED",
  "eventUuid": "33936899-3ca5-5345-9c8e-0ce358bed0a3",
  "timestamp": "2026-09-17T14:02:51.640Z",
  "resource": {
    "paymentUuid": "14c56ab6-d0f0-4b13-9a9a-d9e722aff880",
    "psd2Payment": {
      "status": {
        "status": "PAYMENT_DETAILS_VALID_SETTLED",
        "code": "SETTLED",
        "step": "PAYMENT_DETAILS_SETTLED_VALID"
      }
    }
  }
}

Otras variantes de psd2Payment.status. El resto del cuerpo es idéntico.

FAILED

{
  "status": {
    "status": "PAYMENT_DETAILS_SETTLED_FAILED",
    "code": "SETTLED",
    "step": "PAYMENT_DETAILS_SETTLED_FAILED"
  }
}

REJECTED

{
  "status": {
    "status": "PAYMENT_DETAILS_SETTLED_REJECTED",
    "code": "SETTLED",
    "step": "PAYMENT_DETAILS_SETTLED_REJECTED"
  }
}

PSD2_PAYMENT_STATUS_REJECTED

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "PSD2_PAYMENT_STATUS_REJECTED",
  "eventUuid": "fdeb032c-9380-549e-b05e-23dfa2e90a64",
  "timestamp": "2026-09-17T09:43:18.512Z",
  "resource": {
    "paymentUuid": "6f1e9c3b-2a8d-4e7f-b5c0-9d4a2e8f1b77",
    "psd2Payment": {
      "status": {
        "status": "PAYMENT_STATUS_REJECTED_PAYMENT_REJECTED",
        "code": "REJECTED",
        "step": "PAYMENT_STATUS_REJECTED"
      }
    }
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "PSD2_PAYMENT_STATUS_REJECTED",
  "eventUuid": "fdeb032c-9380-549e-b05e-23dfa2e90a64",
  "timestamp": "2026-09-17T09:43:18.512Z",
  "resource": {
    "paymentUuid": "6f1e9c3b-2a8d-4e7f-b5c0-9d4a2e8f1b77",
    "psd2Payment": {
      "status": {
        "status": "PAYMENT_STATUS_REJECTED_PAYMENT_REJECTED",
        "code": "REJECTED",
        "step": "PAYMENT_STATUS_REJECTED"
      }
    }
  }
}

Eventos de organización

Esta familia existe para Partners y Agentes. Un colaborador da de alta organizaciones cliente y no puede operar en su nombre hasta que están activas; los eventos BUSINESS_* son los que se lo notifican.

Quedan fuera del ciclo transaccional: informan del estado de una organización, no de un cobro. Si integras Zertiban para tu propia organización, no te aportan nada — ya sabes cuándo has completado tu alta.

Evento	Cuándo se genera	Acción sugerida
BUSINESS_ACTIVATED	Una organización cliente completa su alta y queda activa en Zertiban	Emitir un token delegado sobre ella y arrancar la operativa

BUSINESS_ACTIVATED

El resource lleva el UUID de la organización activada en uuid y su estado en status. No incluye externalId, y resource.uuid coincide con metadata.businessUuid:

Sin colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
  },
  "eventType": "BUSINESS_ACTIVATED",
  "eventUuid": "4abd98ec-3b8a-5e1a-b2c0-829fb0125869",
  "timestamp": "2026-09-16T16:12:40.207Z",
  "resource": {
    "uuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "status": "ACTIVE"
  }
}

Con colaborador

{
  "metadata": {
    "apiVersion": "v1",
    "businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "collaboration": {
      "businessUuid": "208da71f-aac8-4a74-8a3d-c07fa7cca9f6"
    }
  },
  "eventType": "BUSINESS_ACTIVATED",
  "eventUuid": "4abd98ec-3b8a-5e1a-b2c0-829fb0125869",
  "timestamp": "2026-09-16T16:12:40.207Z",
  "resource": {
    "uuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334",
    "status": "ACTIVE"
  }
}

Si el alta está atribuida a varios colaboradores, la organización recibe la copia sin collaboration y cada colaborador recibe la suya con su propio identificador (b47d2e91-6c0a-4f5e-8a3d-1e9c7b2f4d58 para el segundo).

resource.uuid es el UUID de la organización cliente que acaba de activarse: el que usarás como target_tenant al pedir el token delegado. metadata.collaboration.businessUuid es tu UUID de colaborador, el del alta atribuida. Si el alta está atribuida a varios colaboradores, cada uno recibe su propia copia con su identificador.

Debes tener el tipo suscrito en tu webhook: tener un endpoint registrado no implica recibirlo. Y deduplica por eventUuid, que es idéntico en todas las copias de un mismo evento y en todos sus reintentos.

¿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
BUSINESS_*	uuid y status de la organización afectada

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.