Introduction
Status Inquiry is the mechanism used by the SIBS Payment Gateway (SPG) to allow the merchant system to retrieve the current state of a transaction on demand.
It enables a pull-based communication model, allowing the merchant to query SPG at any time and obtain a consistent and up-to-date view of the transaction lifecycle.
This capability is essential in scenarios where transaction outcomes are not immediately available or where asynchronous processing is involved, such as user interaction flows or external authorization steps.
Status Inquiry complements the webhook mechanism by providing an explicit query-driven mechanism to validate transaction state, independently of notification timing or delivery guarantees.
The interaction model between webhook notifications and transaction-state validation when additional confirmation is required is further described in E.1.8 – Webhooks vs Status Inquiry (Consistency Model).
Purpose
The purpose of Status Inquiry is to:
- Provide the latest transaction state available through the query API
- Enable explicit validation of transaction outcomes
- Support monitoring and reconciliation of transactions in non-final states
- Act as a fallback mechanism in case of missing or delayed webhook notifications
- Ensure consistency in asynchronous and distributed transaction flows
Status Inquiry APIs provide the latest transaction state available through the query API.
Depending on the payment method and transaction lifecycle stage, the returned transaction state may continue to evolve asynchronously until final resolution is reached.
Webhook notifications, while essential for real-time updates, should not be used as the sole basis for business-critical decisions. Final transaction outcomes should be confirmed using the Status Inquiry APIs when no final webhook is available or when additional confirmation, recovery, reconciliation, or inconsistency resolution is required.
Error codes and response interpretation must follow the model defined in:
Status Inquiry responses combine technical result information (returnStatus) and business transaction state (paymentStatus), and both dimensions must be interpreted according to those chapters.
Inquiry Details extends transaction visibility but does not alter or replace the state-retrieval role of the Status Inquiry mechanism.
Scope of This Section
This section introduces the Status Inquiry mechanism and defines a structured approach to understanding and implementing it within an SPG integration.
The detailed documentation is organized to progressively cover:
- The role of Status Inquiry within the transaction lifecycle
- The technical interface and request model
- The structure and interpretation of response data
- The role of Inquiry Details for extended transaction data retrieval
- The semantics of transaction states and their operational meaning
- The interaction between synchronous queries and asynchronous webhook events
- The recommended strategies for polling, reconciliation, and consistency handling
- The handling of errors, edge cases, and failure scenarios
- The dedicated Inquiry Details endpoint for retrieving extended transaction information
- A complete end-to-end example illustrating the full integration flow
This structure ensures a clear separation between conceptual understanding and implementation details, enabling integrators to build robust, reliable, and production-ready transaction state management logic.
Consistency and reconciliation strategies are further detailed in E.2.6 – Consistency Model: Query vs Webhook.