Overview

A common integration pitfall in SIBS Payment Gateway (SPG) implementations is the incorrect use of Status Inquiry and Webhook notifications.

This occurs when integrators:

• rely exclusively on one mechanism
• misinterpret their roles
• or use them in isolation without proper coordination

In SPG, Status Inquiry and Webhooks are complementary mechanisms, each serving a distinct purpose in the transaction lifecycle. Misusing them leads to incomplete, delayed, or inconsistent transaction state handling.

Distinct Roles of Each Mechanism

SPG provides two primary mechanisms to observe transaction state:

• Webhook notifications
  → provide event-driven updates when transaction state changes occur
• Status Inquiry (Status API)
  → provides on-demand retrieval of the current transaction state

Webhook notifications are designed to:

• deliver near real-time updates
• act as triggers for internal processing
• reflect state transitions as they occur

Status Inquiry is designed to:

• confirm the current state of a transaction
• resolve uncertainty or discrepancies
• provide authoritative validation of the transaction state when required

As demonstrated in F.1 End-to-End Integration Examples, correct implementations rely on both mechanisms working together.

The Core Pitfall

The primary issue arises when integrations treat one mechanism as a complete solution.

Typical incorrect assumptions include:

• “Polling the Status API is sufficient; webhooks are optional”
• “Webhook notifications alone determine the final transaction outcome”

Both assumptions are incorrect.

Using either in isolation leads to incomplete transaction visibility and inconsistent state handling.

Incorrect Implementation Patterns

Misuse of Status Inquiry and Webhooks typically manifests as:

• Implementing polling-only logic without webhook handling
• Ignoring webhook notifications or treating them as optional
• Using webhooks as the sole source of truth without validation
• Not confirming final state through Status Inquiry when required
• Performing excessive or continuous polling instead of event-driven processing
• Failing to handle delayed, duplicated, or out-of-order webhook events

These patterns result from misunderstanding the complementary nature of both mechanisms.

Correct Coordination Model

A correct implementation must combine both mechanisms in a coordinated manner:

• Webhooks
  → act as event triggers indicating that a state change has occurred
• Internal processing
  → updates system state based on received events
• Status Inquiry (when required)
  → confirms the authoritative transaction state, particularly in cases of:
  • uncertainty
  • delayed notifications
  • reconciliation scenarios

This model ensures that:

• updates are processed in near real-time
• final state is confirmed when necessary
• temporary inconsistencies are resolved safely

Relationship with Asynchronous Processing

Because SPG operates under an eventual consistency model, temporary discrepancies may occur between:

• webhook notifications
• status responses
• internal system state

These discrepancies are normal and must be handled explicitly.

A correct implementation must:

• accept that webhook delivery may be delayed or repeated
• treat status responses as authoritative when validating outcomes
• maintain consistency despite timing differences

Failure to handle this relationship correctly leads to incorrect assumptions about transaction state.

Consequences of Incorrect Usage

Incorrect use of Status Inquiry and Webhooks leads to systemic issues:

• Missed transaction updates when relying only on polling
• Delayed processing and poor user experience
• Incorrect state handling when relying only on webhooks
• Increased API load due to excessive polling
• Inconsistent or conflicting transaction states across systems
• Failed reconciliation due to missing or misinterpreted events

These issues are particularly visible under real-world conditions, where asynchronous behavior becomes more pronounced.

Key Principle

Status Inquiry and Webhooks must be used as complementary mechanisms, not as alternatives.

Correct transaction handling requires:

• event-driven processing through webhook notifications
• controlled use of Status Inquiry for validation and reconciliation
• explicit handling of timing differences and eventual consistency

Any integration that relies exclusively on one mechanism will produce incomplete, delayed, or inconsistent transaction outcomes.