This section defines the fundamental concepts and architectural principles required to correctly integrate with the SIBS Payment Gateway. It establishes the conceptual model that governs transaction lifecycle, asynchronous processing, and system interaction patterns.

SIBS Payment Gateway in the Payment Ecosystem

The SIBS Payment Gateway operates as an intermediary layer between merchant systems and financial partners, including acquirers and payment networks.

Merchant systems interact with the gateway through APIs to initiate and manage transactions. The gateway orchestrates the execution of these transactions by routing them to the appropriate SIBS-managed payment services and financial partners. Financial partners remain responsible for the financial operations, including authorization, clearing, and settlement.

This separation ensures that merchants can integrate once with the gateway while supporting multiple payment methods and financial entities.

Core Functional Components

The SIBS Payment Gateway is composed of several logical components that together enable the complete transaction lifecycle:

• API Interface – exposes endpoints for transaction creation, management, and status inquiry
• Payment Orchestration Engine – routes transactions to the appropriate payment services and manages execution flow
• Transaction Lifecycle Management – tracks and updates the state of each transaction throughout its lifecycle
• Notification System (Webhooks) – delivers transaction-status notifications to merchant systems, including when the final outcome is already available in the initial API response
• Status Inquiry Layer – allows merchant systems to retrieve the current state of a transaction independently of notifications

These components work together to provide a consistent and reliable integration model across all supported payment methods.

These components are exposed and used differently depending on the selected integration approach. See B. Integration Models for details.

Generic Transaction Lifecycle

All transactions processed through the SIBS Payment Gateway follow a structured lifecycle, regardless of the payment method or integration model.

A typical transaction progresses through the following stages:

1. Transaction Creation – the merchant system initiates a payment request via the API
2. Customer Interaction (if applicable) – the customer provides payment details or authorizes the transaction
3. Processing and Routing – the gateway forwards the transaction to the appropriate payment service or financial partner
4. Initial Response – the API returns a response reflecting the immediate processing result
5. Asynchronous Completion (if applicable) – the final outcome may be determined after additional processing steps
6. Final State Availability – the definitive transaction state is communicated through a final-state webhook and is also available through the Status Inquiry API. For Multibanco Reference Generation, a webhook may instead communicate a Pending state.

Depending on the payment method, some of these stages may be instantaneous, while others may involve asynchronous processing.

Each transaction is uniquely identified by a transaction identifier assigned by the platform. This identifier must be used as the primary and authoritative reference for all subsequent operations, including status inquiry, capture, refund, and reconciliation processes. Merchant-defined identifiers must not be used as substitutes for this reference when interacting with the platform.

The specific behavior of each stage depends on the selected payment method. See D. Payment Methods for detailed execution models.

Synchronous vs Asynchronous Processing

API interactions with the SIBS Payment Gateway are synchronous at the HTTP level, meaning that each request receives an immediate response.

However, the execution of a payment transaction may involve asynchronous processing. In such cases, the initial API response does not represent the final outcome of the transaction.

For example:

• Card payments may require additional authentication steps
• MB WAY payments require user interaction on a mobile device
• Certain payment methods involve delayed confirmation from financial systems

As a result, integrations must be designed to handle the distinction between:

• Immediate API responses
• Final transaction outcomes

When additional processing is required, implementations must not rely solely on the initial API response to determine the final transaction outcome.

A final outcome may be communicated through a final-state webhook or retrieved through the Status Inquiry API. Integrations must therefore support webhook processing and Status Inquiry as complementary transaction-status mechanisms.

See E. Notifications and Transaction Status for detailed patterns on handling asynchronous transaction updates and reconciliation.

At any given moment during asynchronous processing, the transaction state may still be evolving. Implementations must account for intermediate states and avoid assuming immediate finality.

Webhooks and Status Inquiry

The SIBS Payment Gateway provides two complementary mechanisms to obtain transaction status:

• Webhooks (Notifications) – asynchronous messages sent by the gateway to inform merchant systems of transaction updates
• Status Inquiry API – a synchronous mechanism that allows merchant systems to query the current state of a transaction

Webhooks provide real-time updates and enable event-driven processing. For payment transactions, webhook notifications normally communicate a final transaction state. The relevant exception is Multibanco Reference Generation, for which a webhook may communicate a Pending state.

The Status Inquiry API allows merchant systems to retrieve the current transaction state synchronously. When called after a final-state webhook has been issued, the inquiry reflects that final outcome.

Status Inquiry should be used when the current state must be retrieved explicitly, including recovery scenarios in which webhook delivery or processing is uncertain. It must not be presented as overriding or invalidating a valid final-state webhook.

See E. Notifications and Transaction Status for detailed implementation guidance.

Transaction Finality and Consistency Model

A transaction is considered final only when it reaches a definitive state as determined by the payment method and financial processing outcome.

Because transaction processing may be asynchronous, there may be a delay between the initial API response and the definitive transaction outcome.

Integrations must follow a consistency model based on the following principles:

• Final-state webhooks communicate the definitive transaction outcome and may trigger the corresponding merchant-side processing.
• The Status Inquiry API retrieves the current transaction state and supports explicit verification and recovery when required.
• Multibanco Reference Generation is the relevant exception: its webhook may communicate a Pending state rather than a final outcome.

These complementary mechanisms allow merchant systems to maintain a consistent and reliable view of transaction outcomes.

See C. Meta Information, Codes and Transaction States for details on transaction status models, identifiers, and error interpretation.

Interaction Model

At a high level, the interaction between systems follows a consistent execution and communication pattern:

• The merchant system initiates and manages transactions via API calls
• The SIBS Payment Gateway orchestrates execution and lifecycle management
• Financial partners execute the financial operations
• The gateway communicates transaction outcomes through webhooks, subject to the Pending exception applicable to Multibanco Reference Generation
• The merchant system processes webhook notifications and retrieves the current transaction state through the Status Inquiry API when explicit inquiry is required

This interaction model applies consistently across all integration approaches and payment methods, ensuring a unified and predictable integration experience.

High-Level Interaction Flow
This diagram illustrates the end-to-end interaction between the merchant system, the SIBS Payment Gateway, financial partners, webhook notification flows, and status inquiry mechanisms within a complete transaction lifecycle.

For implementation details, see B. Integration Models and D. Payment Methods.