Overview

The SIBS Payment Gateway (SPG) provides mechanisms for obtaining and tracking transaction status through both asynchronous notifications and active status queries.

This chapter defines the reference framework for how merchant systems receive, interpret, and reconcile transaction state updates across these mechanisms.

It describes:

• How SPG communicates transaction events through webhooks (notifications)
• How merchant systems can retrieve transaction status through API queries
• How to ensure consistency between asynchronous notifications and queried transaction states
• How to design robust processing logic for asynchronous payment flows

These mechanisms are essential for managing the full transaction lifecycle, particularly for payment methods that involve delayed or user-driven confirmation.

Objective

The objective of this chapter is to ensure that integrators correctly implement and coordinate asynchronous notification handling and status querying mechanisms, guaranteeing consistency and reliability in transaction lifecycle management.

Understanding Notification and Transaction Status Mechanisms

SPG supports two complementary approaches for obtaining transaction state information:

Asynchronous Notifications (Webhooks)

SPG can actively notify merchant systems of transaction events by sending webhook notifications to configured endpoints.

These notifications:

• Represent discrete events in the transaction lifecycle
• Are delivered asynchronously
• May be subject to delivery retries and ordering variations
• Are delivered using an at-least-once delivery model, meaning duplicate notifications may occur and must be handled safely by the merchant system

Status Inquiry (Get Status)

Merchant systems can query SPG APIs to retrieve the current state of a transaction.

This approach:

• Provides the authoritative and most up-to-date state of a transaction
• Can be used to validate and reconcile notification-based updates
• Is essential in scenarios where notifications are delayed, missed, or uncertain

Both mechanisms must be used together to ensure a complete and reliable view of transaction state.

Designing for Consistency and Reliability

Because SPG operates with asynchronous processing for certain payment methods, merchants must implement logic that ensures consistency between:

• Events received via webhooks
• Transaction states retrieved via API queries

In particular:

• Notifications should be treated as event triggers, not as the sole source of truth
• The transaction status obtained via API queries should be considered authoritative
• Systems must handle out-of-order or repeated notifications safely
• Idempotent processing must be applied to avoid duplicate effects

Failure to properly coordinate these mechanisms can lead to inconsistent system states, duplicate processing, or missed transaction updates.

In case of discrepancies between received notifications and queried transaction state, systems must resolve inconsistencies by relying on the transaction status obtained through API queries.

Applying This Model in Your Integration

The concepts defined in this chapter apply across all integration models:

• Server-to-Server integrations
• Form Integration flows
• Plugin-based integrations

In practice, merchant systems will:

• Receive webhook notifications for transaction events
• Query transaction status when required (e.g., reconciliation, validation, fallback, or uncertainty in asynchronous flows)
• Correlate events and status using transaction identifiers
• Implement retry-safe and idempotent processing logic
• Maintain consistent internal state across asynchronous updates

This approach ensures reliable handling of both real-time and delayed transaction flows.

Troubleshooting and Operational Considerations

When implementing notification and status mechanisms, common scenarios include:

• Notifications not being received or delayed
• Duplicate or out-of-order webhook events
• Discrepancies between webhook data and queried transaction status
• Uncertain transaction outcomes in asynchronous flows

To address these scenarios, merchants should:

• Log all received notifications and API responses
• Validate webhook integrity where applicable
• Use status queries as the authoritative source of truth when discrepancies or uncertainties occur
• Implement retry and reconciliation mechanisms
• Monitor webhook delivery and processing failures

These practices enable resilient integration behavior and reduce dependency on external support.

Moving Forward

This chapter is organized into the following sections:

E.1 Webhooks (Notifications)

Covers:

• The catalogue of webhook events and normalized payload structures
• JSON schemas and payload formats
• Signature validation and integrity verification (when applicable)
• Guidelines for retries, idempotency, and event validation
• Best practices for processing and logging webhook events

E.2 Status Inquiry / Get Status

Covers:

• Status query endpoints and response payloads
• Recommended polling strategies
• Comparison and reconciliation between queried transaction state and received events
• Best practices for reconciliation and consistency validation

Each section provides detailed technical guidance for implementing these mechanisms in a consistent and reliable way.

Summary

This chapter defines how SPG communicates and exposes transaction state through notifications and status queries.

It enables merchants to consistently:

• Implement reliable asynchronous processing
• Maintain consistent transaction state across systems
• Reconcile event-driven and query-based information
• Handle delayed, duplicated, or missing updates robustly

All integrators should use this chapter as the authoritative reference for handling transaction notifications and status retrieval in SPG integrations.