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 latest transaction state available through the query API
- Can be used to validate and reconcile notification-based updates
- Is essential in scenarios where notifications are delayed, missed, or uncertain
Both mechanisms should be implemented as complementary controls: webhooks provide event-driven notification, while Status Inquiry supports validation, fallback, reconciliation, and operational recovery scenarios when additional confirmation is required.
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 and, when they contain a final
paymentStatus, may be used for business processing - The transaction status obtained through Status Inquiry APIs should be used for reconciliation, fallback, operational recovery, and additional confirmation when required
- 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 using the Status Inquiry APIs to retrieve the latest transaction state available through the query API.
The following diagram illustrates the recommended consistency and reconciliation model between webhook-driven events and transaction status queries.
For a detailed implementation model of webhook and query consistency handling, including reconciliation and inconsistency resolution strategies, see E.1.8 – Webhooks vs Status Inquiry (Consistency Model) and E.2.6 – Consistency Model: Query vs Webhook.
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 to retrieve the latest transaction state available through the query API when discrepancies or uncertainties occur
- Implement retry and reconciliation mechanisms
- Monitor webhook delivery and processing failures
- Maintain operational procedures for reconciliation and recovery of transactions affected by temporary communication failures, delayed notifications, or uncertain asynchronous states
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
- Webhook configuration, delivery monitoring, operational statistics, retry visibility, and failure analysis through the SPG Backoffice
E.2 Status Inquiry / Get Status
Covers:
- Status query endpoints and response payloads
- Extended transaction inquiry through the Inquiry Details API for advanced transaction inspection and operational analysis
Detailed endpoint specifications and advanced inquiry examples are provided in: - 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.