Overview

This section defines how to correctly handle asynchronous processing and consistency behaviors in SIBS Payment Gateway (SPG) integrations.

Many SPG payment flows are not finalized at the time of the initial API response. Instead, they follow an event-driven lifecycle, where the final transaction state is determined after additional steps such as:

• Customer interaction
• External system processing
• Authorization flows

As a result, integrators must implement a consistency model that ensures:

• Correct interpretation of intermediate states
• Reliable detection of final transaction states
• Protection against race conditions and inconsistent data

Asynchronous Processing Model

Description

In asynchronous flows, the initial API response represents only the start of the transaction lifecycle, not its final transaction state.

Typical pattern:

• Initial response:
  • returnStatus.statusCode = "000"
  • paymentStatus = "Pending"
• Final state (asynchronously determined):
  • paymentStatus = "Success" or Declined

Characteristics

• The transaction state evolves over time
• The initial response does not necessarily represent the final business outcome and must not be used alone to determine the final transaction outcome
• The final transaction state may be determined via:
  • Webhooks (push model), and/or
  • Status Inquiry (GET <ROOT_URL>/payments/{transactionID}/status)

For webhook delivery semantics, retry behavior, payload validation, and security recommendations, refer to E.1 – Webhooks and Notifications and its related subchapters.

Common Use Cases

• MB WAY (user approval required)
• Multibanco Reference (external payment)
• Card payments with 3DS
• Two-step flows (AUTH → CAPTURE)

Event Sources and State Updates

SPG provides two complementary mechanisms for obtaining transaction state updates:

Webhooks (Event-Driven Updates)

• Provide near real-time notifications
• Triggered on transaction state changes
• Delivered asynchronously to merchant systems

Characteristics:

• Low latency
• Event-driven architecture
• May be retried by SPG in case of delivery failure

Status Inquiry (Pull-Based Validation)

• Provides the current state of a transaction
• Provides the latest transaction state available through the query API

Endpoint:

GET <ROOT_URL>/payments/{transactionID}/status

Key Principle

Webhooks provide timely updates, while Status Inquiry provides the latest transaction state available through the query API when confirmation, recovery, or reconciliation is required.

Consistency Model

Eventual Consistency

SPG operates under an eventual consistency model:

• State updates may not be immediately synchronized across all channels
• Temporary discrepancies may occur between:
  • Webhook notifications
  • Status Inquiry responses
  • Internal system state

Implications

• A webhook may arrive before the Status Inquiry reflects the final state due to propagation delays across systems
• Multiple updates may be received for the same transaction
• State transitions must be handled as progressive, asynchronous, and potentially non-linear

Race Conditions and Ordering

Problem

Asynchronous systems introduce race conditions, where:

• Webhooks arrive out of order
• Status Inquiry is queried before final state is committed
• Multiple updates are processed concurrently

Examples

• Webhook indicates Success, but a previous Pending state is still stored
• Status Inquiry returns Pending immediately after a webhook indicating Success
• Duplicate webhook deliveries for the same event

Integrator Strategy

• Always treat state transitions as monotonic and forward-only
• Once a transaction reaches a final business state, intermediate or older states must never overwrite it.
• Do not overwrite a final state with an intermediate state
• Implement safeguards against:
  • Out-of-order processing
  • Duplicate events

Recommended Processing Model

A robust integration should follow this model:

1. Initial Request Handling

• Accept initial response
• If paymentStatus = "Pending":
  • Store transaction as pending
  • Do not trigger business actions

2. Webhook Processing

• Receive webhook notification
• Validate authenticity and integrity
• Acknowledge immediately (HTTP 200)

Then:

• Update transaction state
• Trigger downstream processing if final

3. Status Validation

• Use Status Inquiry (GET <ROOT_URL>/payments/{transactionID}/status) when:
  • Webhook is delayed or missing
  • Timeout occurs
  • Final state confirmation is required

4. Reconciliation

• Periodically reconcile transactions in non-final states
• Ensure no transaction remains indefinitely unresolved
• Long-lived Pending transactions should be periodically reviewed according to the merchant’s operational reconciliation policies

Timeout and Uncertain Outcomes

Description

Some transactions may enter uncertain states, such as:

• paymentStatus = "Timeout"
• Long-lived Pending

Integrator Strategy

• Do not assume failure
• Confirm via Status Inquiry when required
• Maintain transaction in a resolvable state
• Include in reconciliation processes

Idempotency and Duplicate Handling

Problem

Asynchronous flows may lead to:

• Duplicate webhook deliveries
• Repeated status checks
• Retried operations

Integrator Strategy

• Implement idempotent processing logic
• Ensure transaction state transitions are processed idempotently and without duplicate business effects.
• Use unique identifiers:
  • transactionID
  • merchantTransactionId

Consistency Rules

• Treat final paymentStatus as the business outcome indicator
• Use Status Inquiry when no final webhook is available or when confirmation, recovery, or reconciliation is required (GET <ROOT_URL>/payments/{transactionID}/status)
• Always support state transitions over time
• Never:
  • Assume synchronous completion
  • Trigger business actions on Pending
  • Overwrite final states with intermediate states

Summary

SPG integrations must be designed for asynchronous and eventually consistent behavior.

This requires:

• Combining event-driven (webhooks) and query-based (Status Inquiry) approaches
• Handling race conditions and duplicate events
• Implementing idempotent and state-aware processing logic

By following this model, integrations achieve:

• Reliable transaction state management
• Accurate financial outcomes
• Robust behavior under real-world conditions