Overview

A critical integration pitfall in SIBS Payment Gateway (SPG) implementations is weak or inconsistent transaction correlation across systems.

This occurs when integrators fail to reliably link all components of a transaction lifecycle across:

• API interactions
• webhook notifications
• status inquiries
• internal business systems

As a result, even when individual components operate correctly, the system loses the ability to reliably reconstruct, track, and validate transaction state end-to-end.

In SPG, transaction correlation is fundamental to ensuring consistency, traceability, and correct lifecycle management.

Nature of Transaction Correlation

Every SPG transaction generates and propagates multiple identifiers that must be consistently managed across all stages of processing.

Key identifiers include:

• transactionID
  → the primary SPG identifier used across all API operations
• merchantTransactionId
  → the merchant-defined identifier used for business-level correlation
• notificationID
  → the unique identifier for each webhook notification

These identifiers appear across:

• API responses
• webhook payloads
• status responses

Correct integration behavior depends on maintaining continuous linkage between these identifiers across all system components.

The Core Pitfall

The core issue arises when integrations fail to maintain a consistent correlation model.

Typical incorrect assumptions include:

• “The transactionID alone is sufficient for all scenarios”
• “Webhook events can be processed independently without linking to prior context”
• “Internal systems can rely on their own identifiers without mapping to SPG identifiers”

These assumptions lead to fragmented views of the same transaction across different parts of the system.

Incorrect Implementation Patterns

Weak transaction correlation typically manifests through the following patterns:

• Not persisting transactionID at checkout creation
• Losing linkage between merchantTransactionId and transactionID
• Processing webhook notifications without correlating them to internal records
• Ignoring or not storing notificationID, preventing idempotent processing
• Using different identifiers inconsistently across system components
• Failing to correlate status responses with previously processed events

These patterns result in a system where transaction data exists but cannot be reliably connected, correlated, or reconciled.

Correct Correlation Model

A correct implementation must establish a consistent and durable correlation model across the entire transaction lifecycle.

This requires:

• Persisting all key identifiers at the earliest possible stage
• Maintaining a one-to-one mapping between:
  • merchantTransactionId (business context)
  • transactionID (SPG context)
• Associating every webhook notification with its corresponding transaction using:
  • transactionID
  • notificationID
• Ensuring that all system components (API layer, processing layer, reconciliation processes) operate on a shared correlation model

Correlation must not be implicit or inferred – it must be explicitly enforced across all stages of the transaction lifecycle.

Relationship with Lifecycle and State Management

Weak correlation directly impacts the ability to correctly manage the transaction lifecycle.

Without proper correlation:

• state transitions cannot be reliably tracked
• asynchronous updates cannot be correctly applied
• lifecycle continuity is broken

This leads to:

• orphan transactions
• duplicated processing
• inconsistent state across systems

As defined in F.7.2 Incomplete Transaction Lifecycle Handling, lifecycle correctness depends on continuous state tracking, which is not possible without proper correlation.

Relationship with Observability and Traceability

Transaction correlation is a prerequisite for effective observability.

Without consistent identifiers:

• logs cannot be linked across system components
• transaction flows cannot be reconstructed
• issues cannot be diagnosed reliably

As emphasized in F.5.2 Correlation and Traceability, correlation enables:

• end-to-end visibility
• auditability
• reliable troubleshooting

Weak correlation therefore directly undermines system operability.

Consequences of Weak Correlation

Failure to maintain proper transaction correlation leads to high-impact operational issues:

• Inability to match webhook events to transactions
• Duplicate or missed processing of transaction updates
• Inconsistent transaction states across systems
• Failed reconciliation between SPG and internal systems
• Loss of auditability and traceability
• Increased operational complexity and support effort

These issues are particularly severe in asynchronous environments, where correlation is the only mechanism that ensures consistency.

Key Principle

Transaction correlation in SPG must be explicit, consistent, and end-to-end.

Correct integration behavior requires:

• persistent and reliable storage of all identifiers
• consistent mapping between business and SPG contexts
• correlation of all events, responses, and state transitions

Any integration that does not enforce a robust correlation model will be unable to guarantee consistency, traceability, or correctness across the transaction lifecycle.