Flows and operations

Shared concepts of flows and operations, structure, states and transitions, common to all Zertiban products.

The concepts of flow and operation form the functional foundation of every Zertiban product. Any integration built on the platform follows this same common structure, regardless of the type of operation or use case implemented.

The architecture is designed to decouple the overall business context from the specific set of actions performed by the end user. This makes it possible to build more flexible, traceable and scalable experiences, where multiple operations can be grouped and managed under a single transactional context.

The system distinguishes between:

• Flow → aggregated business context.
• Operation → individual action executed by the end user.

Both entities have their own identifiers, states, webhook events and lifecycles, independent, yet related to each other.

What is a flow?

A flow is the business container that groups one or more related operations. It is created with a single API call (POST /flow/v1/flows/*) and receives a unique identifier called flowUuid.

The flow represents the overall context of a business interaction. For example:

• A collection process with multiple operations.
• A transactional experience composed of several user actions.
• A set of operations associated with the same functional process.

The state of the flow reflects the aggregated result of all the operations it contains.

Key characteristics

• It has its own independent lifecycle.
• It can be referenced via an externalId for reconciliation with external systems.
• All operations in the flow share visual configuration, expiration and functional behaviour.
• It generates flow.* webhook events when its aggregated state changes.
• It allows multiple operations to be grouped under a single user experience.

Flow structure

Each flow can contain one or many operations, configured individually.

Flow
  ├── Operation 1
  ├── Operation 2
  └── Operation N

Synchronous and asynchronous model

The Zertiban API combines synchronous processing and asynchronous notifications to simplify integration.

• Synchronous: the API call immediately returns all the information you need to operate: operation URLs, identifiers, documents and operational metadata. No polling is required and no additional processing wait is needed to start interacting with the end user.
• Asynchronous: state changes are notified in real time via webhooks. The client system automatically receives events when a user opens an operation, an operation completes, an operation expires or a flow reaches a terminal state. Using webhooks reduces reconciliation latency and avoids integrations based on continuous polling.

Flow states

The flow aggregates the state of all its operations. Its state represents the overall result of the business process.

State	Description	Terminal
CREATED	The flow has been created. No operation has been opened yet.	No
IN_PROGRESS	At least one operation is currently in progress.	No
COMPLETED	All operations have completed successfully.	Yes
PARTIALLY_COMPLETED	At least one operation has completed successfully, but not all.	Yes
NOT_COMPLETED	No operation has completed successfully. Mixed result with no completions.	Yes
REJECTED	All operations have been rejected.	Yes
EXPIRED	All operations have expired.	Yes
CANCELLED	All operations have been cancelled.	Yes

State transitions

From	To	Trigger
CREATED	IN_PROGRESS	An operation moves to OPENED
IN_PROGRESS	COMPLETED	All operations reach COMPLETED
IN_PROGRESS	PARTIALLY_COMPLETED	All operations are terminal and at least one is COMPLETED, but not all
IN_PROGRESS	NOT_COMPLETED	All operations are terminal, none COMPLETED, with mixed results
IN_PROGRESS	REJECTED	All operations end in REJECTED
CREATED / IN_PROGRESS	EXPIRED	All operations end in EXPIRED
CREATED / IN_PROGRESS	CANCELLED	All operations end in CANCELLED

Terminal states are definitive and do not allow any further transitions.

What is an operation?

An operation represents the specific action performed by the end user within a flow. Depending on the Zertiban product, an operation may correspond to an individual payment, a bank authorisation or any isolated transactional interaction.

Each operation has:

• Its own operationUuid.
• Its own independent URL.
• Its own specific lifecycle.
• Its own webhook events.

This makes it possible to monitor and reconcile each user interaction individually.

Key characteristics

• It can be referenced via its own externalId.
• A single flow can contain operations of different types.
• It generates operation.* webhook events when its state changes.
• It has terminal states independent of the other operations in the flow.

Operation states

Each operation evolves through different functional states. The states COMPLETED, REJECTED, EXPIRED and CANCELLED are terminal: once reached, no further transitions occur.

State	Description	Terminal	Webhook
CREATED	The operation has been created. The URL is active but the user has not yet accessed it.	No	OPERATION_CREATED
OPENED	The user has accessed and the operation is in progress.	No	OPERATION_OPENED
COMPLETED	The operation has completed successfully.	Yes	OPERATION_COMPLETED
REJECTED	The user or the bank has rejected the operation.	Yes	OPERATION_REJECTED
EXPIRED	The operation has expired before being completed.	Yes	OPERATION_EXPIRED
CANCELLED	The operation has been cancelled via API or by the system.	Yes	OPERATION_CANCELLED

State transitions

From	To	Trigger
CREATED	OPENED	The user opens the URL
CREATED	EXPIRED	The expiration date is reached (expirationOffset)
CREATED	CANCELLED	PUT/flow/v1/operations/{operationUuid}/cancel
OPENED	COMPLETED	The user completes the operation successfully
OPENED	REJECTED	The user or the bank rejects the operation
OPENED	EXPIRED	The expiration date is reached
OPENED	CANCELLED	PUT/flow/v1/operations/{operationUuid}/cancel (only if there are no pending transactions)

Terminal states are definitive and do not allow any further transitions.

Integration recommendations

Zertiban always recommends using webhooks as the primary mechanism for state synchronisation. Although states can be queried via API, polling introduces higher reconciliation latency, unnecessary traffic and redundant processing.

Webhooks as the primary mechanism.

Webhooks let you react in real time to any state change of operations and flows, enabling more efficient, consistent and scalable integrations.