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 deterministic and authoritative state retrieval

Authoritative Source of Truth

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

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 must be treated as informational events and must not be used as the sole basis for determining the final transaction state.

Under no circumstances should business-critical decisions (e.g., order fulfillment, financial reconciliation) rely exclusively on webhook payloads without validating the transaction state through the Status Inquiry endpoint.

The Status Inquiry endpoint must be used to confirm the final transaction outcome before triggering any irreversible business action.

Recommended Usage Scenarios

Status Inquiry should be used in the following scenarios:

1. Final State Confirmation

After receiving a webhook, to confirm that the transaction has reached its definitive state.

2. Fallback Mechanism

When:

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

3. Active Polling During User Interaction

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

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 state validation

This implies that:

• The latest webhook event may not reflect the current state
• The transaction state returned by the Status Inquiry endpoint is always the most up-to-date representation

For detailed reconciliation strategies, refer to C.7 – State Reconciliation: Query vs Webhook.

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:

• Do not rely exclusively on webhooks for transaction state
• Always validate critical states using Status Inquiry
• 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 deterministic and authoritative access to transaction state.

It ensures:

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

It must be systematically used in conjunction with webhook notifications to guarantee correct transaction lifecycle management and ensure operational reliability.