Overview

This section provides a structured framework to interpret success and error outcomes across all SIBS Payment Gateway (SPG) interactions.

Building on the technical examples presented in this section, it defines how integrators should analyze, classify, and act upon transaction results in real-world conditions. The focus is not only on what the platform returns, but on how those outcomes must be correctly interpreted within a production environment.

Context and Scope

In SPG integrations, transaction outcomes are multi-dimensional and frequently asynchronous. A request that is technically successful (e.g., HTTP 200 with returnStatus.statusCode = "000") does not necessarily correspond to a completed or successful payment.

Depending on the payment method and flow, the same request may result in:

• An immediate successful payment
• A pending state awaiting user interaction or external processing
• A declined transaction
• A timeout or indeterminate outcome

This behavior is particularly relevant for:

• MB WAY flows requiring user approval
• Multibanco Reference payments with delayed settlement
• Card payments involving 3DS authentication
• Two-step payment models (AUTH → CAPTURE)

As such, integrators must adopt a structured interpretation model, avoiding assumptions based solely on the initial API response.

Core Interpretation Model

All SPG responses must be interpreted across two independent layers:

• Technical Layer
  • HTTP status codes
  • returnStatus.statusCode and returnStatus.statusMsg
    These indicate whether the request was accepted and processed at API level
• Business Layer
  • paymentStatus
    This reflects the actual outcome of the payment transaction

In addition to these layers, the HTTP response status must be evaluated as an independent dimension, as it represents the transport-level outcome of the request.

This distinction is essential to prevent premature business actions and ensure consistent transaction handling.

The returnStatus.statusMsg field may indicate “Error” even in scenarios where the transaction was processed and declined at business level. In such cases, paymentStatus must be used as the authoritative indicator of the transaction outcome.

Asynchronous Processing Model

A significant portion of SPG payment flows are asynchronous by design.

Typical lifecycle:

1. Initial API response returns Pending
2. Customer interaction and/or external processing occurs
3. Final state transitions to Success, Declined, or Timeout

The final outcome is obtained via:

• Webhook notifications (recommended), and/or
• Status API (GET <ROOT_URL>/api/v2/payments/{transactionID}/status)

Pending must be treated as a first-class state, explicitly supported in both system logic and user experience.

Source of Truth and Consistency Model

Webhook notifications provide near real-time updates but operate under an eventual consistency model. Temporary discrepancies may occur between:

• Webhook notifications
• Status API responses
• Internal system state

For this reason:

A robust implementation should:

• Acknowledge webhooks immediately
• Use them as event triggers
• Confirm final states via the Status API when required

Error Handling Model

Error handling must be based on clear categorization of failure types, rather than uniform treatment.

The main categories include:

• Validation / Technical Errors
  • Request rejected before processing or during early validation stages
  • Typically caused by invalid payloads or authentication issues
  • Require correction before retry
• Business Errors (e.g., Declined)
  • Valid request, but payment refused
  • Require user action (e.g., different payment method)
• Uncertain Outcomes (e.g., Timeout)
  • Final state not immediately known
  • Require follow-up via Status API and reconciliation logic

This classification enables deterministic and controlled handling strategies.

Operational Considerations

Production-grade integrations must incorporate:

• Idempotent request handling, avoiding duplicate transactions
• Full observability, including payloads, headers, and timestamps
• State reconciliation mechanisms for unresolved transactions
• Protection against invalid state transitions (e.g., Success → Pending)
• Explicit handling of partial flows (e.g., AUTH without CAPTURE)

These practices are critical to ensure consistency across transaction lifecycle management and financial reconciliation.

Relationship with Other Chapters

This section complements:

• Chapter C. Meta Information, Codes and Transaction States, which defines the structure and semantics of status and error fields
• Chapter E.1 Webhooks (Notifications), which defines how asynchronous updates are delivered and processed
• Section F.2 Requests and Responses (Annotated), which provides concrete payload examples referenced in the scenarios covered here

While those sections define what the platform returns, this section defines how those outcomes must be interpreted and acted upon.

Summary

Handling success and error scenarios in SPG integrations requires:

• A strict separation between technical processing and business outcome
• Explicit support for asynchronous and eventual consistency patterns
• Deterministic mapping from observed states to integrator actions

By applying these principles, integrations become:

• Robust under real-world conditions
• Consistent across payment methods and flows
• Aligned with SPG operational semantics