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 and Inquiry Details
  → provide transaction-state confirmation when required and extended lifecycle visibility where applicable

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 transaction-state confirmation when required

Extended transaction diagnostics and operation-level lifecycle visibility may additionally require the use of Inquiry Details, as described in E.2.10 – Inquiry Details API.

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

See E.1 – Webhooks (Notifications) and E.2 – Status Inquiry / Get Status for detailed operational guidance regarding webhook processing, polling strategies, and transaction validation behavior.

The Core Pitfall

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

Typical incorrect assumptions include:

• “Polling the Status Inquiry 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.

The final transaction state must be validated through coordinated use of webhook notifications and Status Inquiry, with Status Inquiry / Get Status used when confirmation, recovery, or reconciliation is required.

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 sufficient final confirmation without validation
• Not confirming final state through Status Inquiry / Get Status 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 latest transaction state available through the query API, 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 deterministically

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 the latest transaction state available through the query API 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.