Overview

The Status Inquiry (Get Status) mechanism provides merchants with a synchronous method to retrieve the current state of a transaction directly from the SIBS Payment Gateway.

The Status Inquiry mechanism operates using the SIBS-generated transactionID, which uniquely identifies the transaction within the SIBS Payment Gateway and must be used for all status retrieval operations.

Its primary role is to ensure state accuracy, consistency, and finality validation across the entire transaction lifecycle, complementing the asynchronous nature of webhook notifications.

Status Inquiry operations must always be executed server-to-server and must not be exposed directly to client-side environments.

Positioning within the Transaction Lifecycle

In the SIBS Payment Gateway architecture, transaction state management relies on two complementary mechanisms:

• Asynchronous Notifications (Webhooks) → Event-driven updates pushed by SIBS
• Status Inquiry (Get Status) → On-demand state retrieval initiated by the merchant

These mechanisms operate together to provide a robust and fault-tolerant state management model.

Conceptual Role

• Webhooks provide near real-time visibility of transaction events
• Status Inquiry provides explicit query-driven transaction-state validation when required

Transaction State Query Model

The Status Inquiry APIs provide the latest transaction state available through the query API.

This is particularly important because:

• Webhooks may be:
  • Delivered out of order (event ordering is not guaranteed)
  • Delayed
  • Temporarily unavailable
  • Delivered more than once
• Transaction state may evolve after a webhook is emitted (e.g., additional processing steps)

Webhook notifications are event notifications and may contain a final paymentStatus that can be used for business processing.

Business-critical decisions should be based on a final webhook paymentStatus or on Status Inquiry validation when no final webhook is available or when additional confirmation is required.

The Status Inquiry APIs should be used to confirm the final transaction outcome before triggering irreversible business action when no final webhook is available or when additional confirmation is required.

Recommended Usage Scenarios

Status Inquiry should be used in the following scenarios:

1. Final State Confirmation

After receiving a webhook, when additional confirmation is required or when the webhook does not provide a final paymentStatus.

2. Fallback Mechanism

When:

• No webhook is received
• Webhook delivery fails
• Internal processing errors occur

3. Active Polling During Interactive Payment Flows

During interactive payment flows requiring real-time user feedback (e.g., checkout waiting screens).

4. Reconciliation Processes

For:

• Batch validation
• Periodic reconciliation jobs
• Audit and financial control processes

5. Extended Transaction Investigation

When additional transaction data is required beyond the standard Status Inquiry response, the Inquiry Details API may be used to retrieve extended transaction information.

Inquiry Details must not replace Status Inquiry for final state validation and must not be used to determine transaction outcomes under any circumstances.

Interaction with Payment Flows

The role of Status Inquiry varies depending on the payment flow:

One-Off Payments

• Used to confirm completion after user interaction
• Particularly relevant for asynchronous methods (e.g., MB WAY, Multibanco Reference)

Two-Step Payments (AUTH → CAPTURE)

• Used to validate:
  • Authorization success
  • Capture completion

Recurring Payments (MIT / Mandates)

• Used to:
  • Validate execution of Merchant Initiated Transactions
  • Confirm mandate-based collections

Status Inquiry operations are idempotent and can be safely repeated without side effects. Integrators should leverage this property when implementing retry mechanisms and polling strategies.

Consistency Model

The SIBS Payment Gateway follows an event-driven eventual consistency model:

• Webhooks provide event notifications
• Status Inquiry provides transaction-state validation when additional confirmation is required

This implies that:

• The latest webhook event may not reflect the current state
• The transaction state returned by the Status Inquiry APIs represents the latest state available through the query API at query time
• Depending on the payment method and transaction lifecycle stage, the returned state may still evolve asynchronously until final operational resolution is reached

For detailed reconciliation and transaction-state consistency strategies, refer to E.2.6 – Consistency Model: Query vs Webhook and E.1.8 – Webhooks vs Status Inquiry (Consistency Model).

For detailed definitions of transaction states and their semantics, refer to C.3 – Transaction States and Operational Meaning.

Key Principles for Integrators

To ensure a reliable integration, merchants must adhere to the following principles:

• Use final webhook paymentStatus when provided; use Status Inquiry when no final webhook is available or when additional confirmation is required
• Validate critical states using Status Inquiry when no final webhook is available or when additional confirmation is required
• Implement retry and fallback mechanisms for state retrieval
• Design systems to handle eventual consistency and state transitions

Summary

The Status Inquiry mechanism is a critical component of the SIBS Payment Gateway integration model, providing query-driven access to the latest transaction state available through the query API.

It ensures:

• Accurate validation of transaction outcomes
• Resilience against asynchronous delivery and notification issues
• Consistency across distributed and event-driven flows

It should be used in conjunction with webhook notifications when explicit validation, fallback, reconciliation, or additional confirmation is required to guarantee correct transaction lifecycle management and ensure operational reliability.