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

For the operational meaning and merchant actions associated with each state, refer to C.3 – Transaction States and Operational Meaning.

State Model

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

Primary States

• Pending
• Success
• Declined
• Error
• Timeout

State transitions are not guaranteed to be linear, and intermediate states may be skipped depending on the payment method and processing flow.

State Categories

1. Non-Final States

These represent ongoing processing:

• Pending → waiting for external action (e.g., MB WAY approval)

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            → Success
Pending            → Declined
Pending            → Timeout
Pending            → Error

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

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 may be communicated later through a webhook notification
• the current transaction state may also be retrieved through Status Inquiry when required

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

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 modify the original transaction state
• must be treated as separate operations with their own lifecycle

State Consistency and Reconciliation

Multiple Sources of Truth

Transaction state may be obtained from:

• synchronous API responses
• webhook notifications
• status API queries

Complementary Status Mechanisms

Webhook notifications normally communicate final transaction states.

The Status Inquiry API retrieves the current transaction state:

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

Consistency Rule

When webhook delivery or processing is uncertain, retrieve the current state through Status Inquiry. A valid final-state webhook must not be presented as being overridden or invalidated by Status Inquiry.

For a complete reconciliation strategy across asynchronous flows, refer to C.7 – State Reconciliation: Query vs Webhook.

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

Rule 3 – Handle Timeouts Explicitly

Timeouts must be treated as:

• incomplete transactions
• eligible for retry

Rule 4 – Verify When Required

Before final action, use Status Inquiry when the current state must be retrieved explicitly or webhook delivery/processing is uncertain.

Implementation Checklist

Merchant systems must:

• support asynchronous state transitions
• store transaction state updates reliably
• process webhook events idempotently
• use Status Inquiry for explicit verification or recovery when required
• 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