Overview

The SIBS Payment Gateway operates using an event-driven, eventually consistent model for transaction state management.

In this model:

• Webhooks provide asynchronous event notifications
• Status Inquiry APIs (Query) provide synchronous state retrieval

These two mechanisms serve complementary roles and must be used together to ensure correct, reliable, and consistent transaction processing.

Conceptual Model

Transaction state visibility is achieved through two distinct mechanisms:

• Event Stream (Webhooks) → reflects events as they occur
• State Snapshot (Status Inquiry APIs) → reflects the current known state

These mechanisms are not guaranteed to be synchronized at all times.

Temporary inconsistencies between webhook events and queried state are expected and must be handled explicitly by the integration logic.

Transaction State Query Model

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

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

Important:

• Business-critical decisions may rely on a final webhook paymentStatus or on Status Inquiry validation when no final webhook is available or when additional confirmation is required
• Final transaction outcomes should be validated using the Status Inquiry APIs when no final webhook is available or when additional confirmation is required

Consistency Characteristics

The system exhibits the following consistency properties:

• Eventual consistency between event notifications and queryable state
• Non-deterministic delivery timing of webhook events
• No guarantee of event ordering
• Possible duplication of webhook events

As a result, temporary inconsistencies between webhook data and queried state are expected.

Typical Inconsistency Scenarios

Scenario 1: Webhook arrives before final state is available

• Multibanco Reference generation notification may indicate Pending before final payment completion

Guidance:

• Continue polling
• Wait for final state

Scenario 2: Status updated before webhook delivery

• Status Inquiry APIs return Success
• Webhook has not yet been received

Guidance:

• Use the Status Inquiry APIs to retrieve the latest transaction state available through the query API
• Do not block processing waiting for webhook

Scenario 3: Webhook delivered out of order

• Older event received after a newer one

Guidance:

• Use Status Inquiry APIs to resolve ordering inconsistencies when required
• Do not assume webhook order reflects lifecycle order

Scenario 4: Duplicate webhook delivery

• Same webhook received multiple times

Guidance:

• Implement idempotent processing
• Avoid duplicate business actions

Webhook retry behavior, delivery guarantees, and idempotency handling are described in E.1.3 – Webhook Delivery, Retries and Idempotency.

Scenario 5: Missing webhook

• No webhook received due to delivery failure

Guidance:

• Use polling as fallback
• Query transaction state until final

Polling strategies, backoff models, and stop conditions are described in E.2.5 – Polling Strategy and Best Practices.

State Reconciliation Strategy

To ensure consistent and reliable transaction handling, integrators must implement a reconciliation strategy based on the following principles:

• Validate transaction state using the Status Inquiry APIs when no final webhook is available or when additional confirmation, recovery, reconciliation, or inconsistency resolution is required
• Use webhooks as event notifications; when they contain a final paymentStatus, that status can be used for business processing
• Reconcile differences between:
  • Last received webhook state
  • Latest queried transaction state

Recommended Integration Pattern

A robust integration should follow this pattern:

1. Initiate transaction
2. Start polling (short-lived) for immediate feedback
3. Receive webhook notification(s)
4. Query Status Inquiry APIs
5. Confirm final state
6. Trigger business action

Decision Model

Condition	Action
Webhook received	Validate state via the Status Inquiry APIs
Polling detects a typically final state	Validate operational context and proceed with business logic when appropriate
Webhook and query disagree	Trust the Status Inquiry APIs
No webhook received	Continue polling within limits

Handling Transient States

While the transaction is in a non-final state:

• Pending

Integrators must:

• Continue polling according to defined strategy
• Wait for either:
  • Final state via query
  • Webhook confirmation

Handling Final States

Final states include:

• Success
• Declined

Potentially final depending on context:

• Error
• Timeout

Error and Timeout states may still require operational reconciliation or asynchronous validation depending on the payment method and transaction lifecycle stage.

Guidelines:

• Only final states should trigger irreversible business actions
• Final state must be confirmed via the Status Inquiry APIs

Idempotency and Safe Processing

Due to possible duplication and reordering:

• Webhook processing must be idempotent
• Business actions must not be executed multiple times
• Transaction state evaluation must be repeatable and safe

Integration Anti-Patterns

The following practices must be avoided:

• Relying exclusively on webhook payloads that do not contain a final paymentStatus
• Ignoring the Status Inquiry APIs validation
• Assuming webhook delivery order
• Triggering business actions on transient states
• Polling indefinitely without stop conditions

Key Integration Principles

• Use the Status Inquiry APIs to retrieve the latest transaction state available through the query API when required
• Use webhooks as event notifications; when they contain a final paymentStatus, they may be used for business processing
• Design for eventual consistency and temporary inconsistencies
• Implement reconciliation logic between query and webhook
• Ensure idempotent processing of events

Summary

The SIBS Payment Gateway consistency model is based on event-driven notifications combined with transaction-state queries when required.

By correctly combining:

• Webhooks (event stream)
• Status Inquiry APIs (state validation)

Integrators can ensure:

• Accurate transaction state handling
• Resilient and fault-tolerant systems
• Correct execution of business processes

This model is essential for achieving reliable, scalable, and auditable payment integrations.

The Inquiry Details API may expose Merchant Initiated Transaction (MIT) attributes, including type and amount qualifiers, providing additional context for recurring and subsequent transactions.

This information complements, but does not replace transaction-state validation through the Status Inquiry APIs when required.