Overview

The SIBS Payment Gateway operates using an event-driven, eventually consistent model for transaction state management.

In this model:

• Webhooks provide asynchronous event notifications
• Status Inquiry (Query) provides synchronous state retrieval

These two mechanisms serve complementary roles and must be used together to ensure correct, reliable, and consistent transaction processing.

Conceptual Model

Transaction state visibility is achieved through two distinct mechanisms:

• Event Stream (Webhooks) → reflects events as they occur
• State Snapshot (Status Inquiry) → reflects the current known state

These mechanisms are not guaranteed to be synchronized at all times.

Temporary inconsistencies between webhook events and queried state are expected and must be handled explicitly by the integration logic.

Authoritative Source of Truth

The Status Inquiry endpoint is the only authoritative source of truth for the current and final state of a transaction.

Webhooks must be treated as informational event notifications, not as definitive state indicators.

Important:

• Business-critical decisions must not rely exclusively on webhook payloads
• Final transaction outcomes must always be validated using Status Inquiry

Consistency Characteristics

The system exhibits the following consistency properties:

• Eventual consistency between event notifications and queryable state
• Non-deterministic delivery timing of webhook events
• No guarantee of event ordering
• Possible duplication of webhook events

As a result, temporary inconsistencies between webhook data and queried state are expected.

Typical Inconsistency Scenarios

Scenario 1: Webhook arrives before final state is available

• Webhook indicates an intermediate state
• Status Inquiry still returns Pending or InProcessing

Guidance:

• Continue polling
• Wait for final state

Scenario 2: Status updated before webhook delivery

• Status Inquiry returns Success
• Webhook has not yet been received

Guidance:

• Treat Status Inquiry as authoritative
• Do not block processing waiting for webhook

Scenario 3: Webhook delivered out of order

• Older event received after a newer one

Guidance:

• Always rely on latest state from Status Inquiry
• Do not assume webhook order reflects lifecycle order

Scenario 4: Duplicate webhook delivery

• Same webhook received multiple times

Guidance:

• Implement idempotent processing
• Avoid duplicate business actions

Scenario 5: Missing webhook

• No webhook received due to delivery failure

Guidance:

• Use polling as fallback
• Query transaction state until final

State Reconciliation Strategy

To ensure consistent and reliable transaction handling, integrators must implement a reconciliation strategy based on the following principles:

• Always validate transaction state using Status Inquiry
• Use webhooks as triggers, not as final state confirmation
• Reconcile differences between:
  • Last received webhook state
  • Latest queried transaction state

Recommended Integration Pattern

A robust integration should follow this pattern:

1. Initiate transaction
2. Start polling (short-lived) for immediate feedback
3. Receive webhook notification(s)
4. Query Status Inquiry endpoint
5. Confirm final state
6. Trigger business action

Decision Model

Condition	Action
Webhook received	Validate state via Status Inquiry
Polling detects final state	Proceed with business logic
Webhook and query disagree	Trust Status Inquiry
No webhook received	Continue polling within limits

Handling Transient States

While the transaction is in a non-final state:

• Pending
• InProcessing

Integrators must:

• Continue polling according to defined strategy
• Wait for either:
  • Final state via query
  • Webhook confirmation

Handling Final States

Final states include:

• Success
• Declined
• Error
• Timeout

Guidelines:

• Only final states should trigger irreversible business actions
• Final state must be confirmed via Status Inquiry

Idempotency and Safe Processing

Due to possible duplication and reordering:

• Webhook processing must be idempotent
• Business actions must not be executed multiple times
• Transaction state evaluation must be repeatable and safe

Integration Anti-Patterns

The following practices must be avoided:

• Relying exclusively on webhook payloads for final state
• Ignoring Status Inquiry validation
• Assuming webhook delivery order
• Triggering business actions on transient states
• Polling indefinitely without stop conditions

Key Integration Principles

• Always treat Status Inquiry as the source of truth
• Use webhooks as event notifications, not final state indicators
• Design for eventual consistency and temporary inconsistencies
• Implement reconciliation logic between query and webhook
• Ensure idempotent processing of events

Summary

The SIBS Payment Gateway consistency model is based on event-driven notifications combined with authoritative state queries.

By correctly combining:

• Webhooks (event stream)
• Status Inquiry (state validation)

Integrators can ensure:

• Accurate transaction state handling
• Resilient and fault-tolerant systems
• Correct execution of business processes

This model is essential for achieving reliable, scalable, and auditable payment integrations.