Correlation and traceability ensure that all events related to a transaction can be linked, followed, and reconstructed across the full processing lifecycle.

They are essential to provide a coherent view of system behavior, particularly in distributed and asynchronous environments where multiple events may affect the same transaction over time.

Correlation Principles

All events associated with a transaction must be consistently identifiable and linkable.

• The Merchant system must:
  • Use consistent identifiers across all system components
  • Ensure that each transaction can be uniquely and consistently identified across all interactions
  • Maintain a clear mapping between external and internal identifiers

Correlation must enable the Merchant system to:

• Link API requests and responses
• Associate asynchronous notifications with their originating transactions
• Relate internal processing steps to external events

Without proper correlation, logs cannot be reliably interpreted, and transaction behavior cannot be accurately reconstructed. Logging practices defined in F.5.1 Logging Principles must ensure that all relevant identifiers are consistently captured.

Correlation Identifiers

Correlation relies on a defined set of identifiers that must be consistently used across all interaction points.

The most relevant identifiers include:

• transactionID
  Primary identifier for the transaction across all API interactions and system events
• merchantTransactionId
Business-level identifier used to associate transactions with internal systems or orders
• notificationID
  Unique identifier for asynchronous notifications, used to detect and handle duplicate events

These identifiers must be:

• Persisted reliably
• Included in all relevant log entries
• Propagated across all processing stages

Their structure and semantics are defined in F.2 Requests and Responses (Annotated) and must not be reinterpreted or modified at the logging or monitoring level.

Correlation Across Interaction Points

Correlation must be maintained across all interaction points involved in transaction processing.

• The Merchant system must correlate:
  • API requests and corresponding responses
  • Webhook notifications and the related transaction
  • Status inquiry results and prior transaction events

Each event must be:

• Associated with the correct transaction
• Linked to preceding and subsequent events

This ensures that the full lifecycle of a transaction can be traced, even when events occur at different times or through different channels.

Traceability of Asynchronous Events

Asynchronous processing requires explicit traceability mechanisms.

• The Merchant system must:
  • Track each notification from reception to processing
  • Use identifiers (e.g., notificationID) to detect duplicate or repeated events
  • Ensure that asynchronous events are correlated with the correct transaction

Asynchronous events may:

• Arrive multiple times
• Be delayed
• Be processed independently from the original request

Traceability must ensure that these events can be correctly interpreted and reconciled within the overall transaction context, following the asynchronous processing model defined in F.3 Success and Error Scenarios.

End-to-End Traceability

Traceability must enable reconstruction of the complete transaction lifecycle.

• The Merchant system must ensure that:
  • All relevant events are logged and correlated
  • The sequence of operations can be reconstructed from logs
  • Execution paths and decision points can be identified

End-to-end traceability supports:

• Troubleshooting and root cause analysis
• Validation of transaction behavior
• Reconciliation of transaction outcomes

In scenarios involving retries, asynchronous updates, or delayed final states, traceability becomes essential to determine the actual progression of the transaction.

Consistency with Transaction Lifecycle

Correlation must reflect the actual lifecycle of the transaction.

• The Merchant system must:
  • Ensure that correlated events are consistent with the expected transaction progression
  • Avoid associating unrelated events with the same transaction
  • Maintain a coherent and accurate representation of transaction state evolution

The interpretation of transaction states and outcomes must follow the model defined in F.3 Success and Error Scenarios, ensuring that correlated events are correctly understood in context.

Security and Integrity of Correlation Data

Correlation data must be reliable and protected.

• The Merchant system must ensure that:
  • Identifiers used for correlation are not altered or misused
  • Correlation is based on validated and trusted inputs
  • Logs accurately and consistently reflect the relationship between events

Incorrect or manipulated correlation may lead to:

• Misinterpretation of transaction behavior
• Incorrect reconciliation
• Operational and financial inconsistencies

Key Principle

Correlation and traceability must be enforced as system-wide capabilities across all components, ensuring that every transaction can be followed across all interaction points, enabling accurate reconstruction, interpretation, and validation of system behavior under real-world conditions.