Overview

This section defines the allowed state transitions for transactions processed through the SIBS Payment Gateway (SPG), including:

• normal processing flows
• asynchronous state evolution
• exception scenarios
• timeout and abandonment cases
• post-processing reversals

Its objective is to provide a deterministic model that allows integrators to:

• understand how a transaction evolves over time
• correctly interpret intermediate states
• safely react to state changes
• handle edge cases and inconsistencies

State Model

Transactions in SPG evolve through a set of well-defined states, represented by the paymentStatus field.

Primary States

• Pending
• InProcessing
• Success
• Declined
• Error
• Timeout

State Categories

1. Non-Final States

These represent ongoing processing:

• Pending → waiting for external action (e.g., MB WAY approval)
• InProcessing → being processed internally by SPG

These states are not final and must not trigger business actions.

2. Final States

These represent terminal outcomes:

• Success → transaction completed successfully
• Declined → transaction rejected at business level
• Error → technical failure
• Timeout → transaction not completed in time

Once a transaction reaches a final state, no further transitions are expected (with limited exceptions described below).

State Transition Matrix

The following matrix defines the valid transitions between states:

Initial State      → Next Possible States
--------------------------------------------
Pending            → InProcessing
Pending            → Success
Pending            → Declined
Pending            → Timeout
Pending            → Error

InProcessing       → Success
InProcessing       → Declined
InProcessing       → Error
InProcessing       → Timeout

Success            → (terminal)
Declined           → (terminal)
Error              → (terminal)
Timeout            → (terminal)

Transition Semantics

Pending → Success

Occurs when:

• user completes authorization (e.g., MB WAY, 3DS)
• external system confirms transaction

Pending → Declined

Occurs when:

• user explicitly rejects the payment
• authorization fails after initiation

Pending → Timeout

Occurs when:

• user does not act within allowed time window
• session expires

Pending → Error

Occurs when:

• technical failure happens during asynchronous processing

InProcessing → Success / Declined / Error

Represents internal SPG processing completion, where the final outcome is determined.

Asynchronous Behavior

Many SPG payment methods are asynchronous by nature, including:

• MB WAY
• 3DS card flows
• Multibanco Reference

Key Characteristics

• initial response often returns:
  • paymentStatus = Pending
• final state is delivered later via:
  • webhook notification
  • status API

Exception Scenarios

1. Timeout After Pending

A transaction may remain in Pending and transition to:

Pending → Timeout

This does not imply failure due to system error, but rather lack of user action.

2. Post-Authorization Decline

In some cases:

Pending → Success → Declined

or directly:

Pending → Declined

This occurs when:

• authorization step succeeds
• but final settlement or validation fails

3. Technical Failure During Processing

Pending → Error
InProcessing → Error

Indicates:

• system failure
• integration issue
• external dependency failure

Reversal and Post-Final Adjustments

Although final states are terminal from a transaction processing perspective, external operations may alter the financial outcome, including:

• refunds
• reversals
• cancellations

These operations:

• do not change the original transaction state
• are represented as new transactions or operations

State Consistency and Reconciliation

Multiple Sources of Truth

Transaction state may be obtained from:

• synchronous API responses
• webhook notifications
• status API queries

Authoritative Source

The Status API must be considered the final authority:

GET https://spg.qly.site1.sibs.pt/api/v2/payments/{transactionID}/status

Consistency Rule

When discrepancies occur:

• always trust the latest status API response
• treat webhook notifications as event triggers, not final truth

Operational Rules

Rule 1 – Act Only on Final States

Business actions must only be triggered when:

• paymentStatus is:
  • Success
  • Declined
  • Error
  • Timeout

Rule 2 – Do Not Act on Pending States

Never:

• ship goods
• confirm orders
• trigger fulfillment

while in:

• Pending
• InProcessing

Rule 3 – Handle Timeouts Explicitly

Timeouts must be treated as:

• incomplete transactions
• eligible for retry

Rule 4 – Always Reconcile

Before final action:

• confirm state using Status API

Implementation Checklist

Merchant systems must:

• support asynchronous state transitions
• store transaction state updates reliably
• process webhook events idempotently
• reconcile states using Status API
• handle all final states explicitly
• avoid assumptions based on initial responses

Summary

SPG transactions follow a state-driven lifecycle, where:

• initial states are often non-final and asynchronous
• final outcomes are determined over time
• multiple transitions may occur before completion

Correct implementation of this model ensures:

• accurate handling of all transaction scenarios
• resilience to asynchronous behavior
• proper treatment of edge cases and exceptions
• consistent and predictable payment processing logic