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 outcomes
• 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 outcome.

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 is not authoritative and must not be used to determine the final transaction outcome
• Final outcome must be obtained via:
  • Webhooks (push model), and/or
  • Status API (GET <ROOT_URL>/api/v2/payments/{transactionID}/status)

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 API (Pull-Based Validation)

• Provides the current state of a transaction
• Must be used as the authoritative source of truth

Endpoint:

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

Key Principle

Webhooks provide timely updates, while the Status API provides the authoritative transaction state.

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 API responses
  • Internal system state

Implications

• A webhook may arrive before the Status API 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 and non-linear

Race Conditions and Ordering

Problem

Asynchronous systems introduce race conditions, where:

• Webhooks arrive out of order
• Status API 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 API 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
• 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 API (GET <ROOT_URL>/api/v2/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

Timeout and Uncertain Outcomes

Description

Some transactions may enter uncertain states, such as:

• paymentStatus = "Timeout"
• Long-lived Pending

Integrator Strategy

• Do not assume failure
• Always confirm via Status API
• 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 each transaction is processed exactly once per state transition
• Use unique identifiers:
  • transactionID
  • merchantTransactionId

Consistency Rules

• Always treat paymentStatus as the business source of truth
• Always confirm final states using the Status API (GET <ROOT_URL>/api/v2/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 API) 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