Overview

The SIBS Payment Gateway (SPG) defines a structured and consistent model for transaction meta information, status codes, error codes, and state transitions, enabling merchant systems to deterministically interpret, control, and manage payment operations.

This chapter establishes the reference framework used across all SPG integrations and defines:

• How transaction data is structured and returned by SPG
• The functional meaning of key response fields
• How transaction states and their transitions are represented and evolve over time
• How transaction status codes and error codes are communicated
• How error payloads are structured and should be handled
• How merchant systems should interpret and act upon SPG responses
• How transaction states obtained via API queries relate to events received through webhook notifications
• How both sources must be reconciled to determine the final transaction state

These elements are common to all payment methods and integration models and form the basis for reliable, deterministic, and consistent payment processing.

The correct interpretation of this information is essential to ensure:

• Consistent transaction handling
• Accurate business decision-making (e.g., order fulfillment, retries, cancellations)
• Proper handling of asynchronous payment flows
• Reduced operational errors and support dependency

Understanding Transaction Information and States

All interactions with SPG result in structured responses containing transaction-related data.

These responses include key elements such as:

• Unique transaction identifiers (transactionID)
• Payment type and method (paymentType, paymentMethod)
• Transaction status (paymentStatus)
• Execution and processing details (execution)
• Optional elements such as tokens or mandates

Each field has a well-defined functional meaning and must be interpreted according to its documented semantics. These elements follow consistent semantics across payment methods, although field presence and behavior may vary depending on the payment flow.

A central concept in SPG is the transaction state, represented by the paymentStatus field.

This field reflects the current lifecycle stage of a transaction and must be used as the authoritative indicator for:

• Whether a payment has been successfully completed
• Whether further action is required (e.g., capture, retry, user interaction)
• Whether a transaction is still in progress or has reached a final outcome

In asynchronous scenarios, this state must be validated against the latest information available through server-to-server status queries, which should be considered the authoritative source of truth.

Transaction states evolve over time according to defined state transitions, which may include:

• Immediate transitions (e.g., direct success or decline)
• Asynchronous transitions (e.g., pending → success in MB WAY or Multibanco)
• Post-payment transitions (e.g., authorization → capture, refund)

Merchant systems must rely on these states and transitions, rather than assumptions, timing expectations, or client-side heuristics, to drive business logic.

Interpreting SPG Responses

When processing SPG responses, merchant systems should consider the following aspects:

• The transaction status and whether it represents a final or non-final state.
  • Final states represent a definitive outcome (e.g., Success, Declined, Error), while
  • non-final states (e.g., Pending, InProgress) require further processing or external interaction.
• Only final states should be used to trigger irreversible business actions (e.g., order fulfillment, settlement, or service activation).
• The payment type, which defines the operational context (e.g., AUTH vs PURS vs MIT)
• The expected transaction flow and possible follow-up operations (e.g., capture, refund)
• The possibility of asynchronous processing, depending on the payment method
• The presence of status codes or error codes requiring specific handling
• The distinction between technical success (e.g., successful request processing) and business outcome (e.g., payment approved or declined)

Different payment methods may exhibit different behaviors (e.g., immediate vs delayed confirmation), but all follow the same underlying principles defined in this chapter.

Status Codes and Error Handling

SPG responses typically include status codes and error codes that provide additional context about the outcome of an operation.

These codes provide a standardized classification of outcomes and must be used to distinguish between:

• Successful operations
• Business-level declines (e.g., insufficient funds, user rejection)
• Technical errors (e.g., invalid request, signature issues)

Error responses follow a structured and predictable format and typically include:

• An error code identifying the condition
• A descriptive message
• Additional details to support diagnosis

Merchant systems must implement appropriate handling strategies based on these codes, including:

• Informing the customer in case of business declines
• Retrying operations when applicable, particularly in cases of transient technical errors, while ensuring idempotency and avoiding duplicate processing in final states
• Logging and monitoring technical errors
• Triggering fallback or recovery mechanisms
• Differentiating between retryable and non-retryable conditions based on error classification

Applying This Model in Your Integration

The concepts defined in this chapter apply uniformly across:

• Server-to-Server integrations
• Form Integration flows
• Plugin-based integrations

All SPG APIs and flows rely on the same transaction model, status semantics, and error handling principles.

In practice, merchant systems must:

• Receive transaction data through API responses or redirects
• Persist and track the transactionID for all operations
• Evaluate the paymentStatus to determine next actions
• Handle final and non-final states appropriately
• Implement logic for asynchronous flows and follow-up operations
• Handle error scenarios based on status and error codes
• Reconcile webhook notifications with transaction status queries to ensure consistency of the final transaction state

Correct implementation of this model is essential to ensure consistency across payment methods and use cases.

Merchant systems must not rely solely on client-side results or redirects and must always validate the final transaction state using server-to-server mechanisms when required.

Troubleshooting and Operational Guidance

This chapter also provides guidance for diagnosing and resolving common integration scenarios.

Typical situations include:

• Transactions remaining in a non-final state (e.g., Pending or InProgress)
• Payment failures due to business or technical reasons
• Inconsistencies between expected and actual transaction states
• Errors during post-payment operations (e.g., capture or refund)

To support troubleshooting, merchants should:

• Log all requests and responses exchanged with SPG
• Track transaction identifiers across all operations
• Validate request parameters and authentication headers
• Use transaction status queries as the authoritative mechanism to resolve transaction state, particularly in asynchronous flows or uncertain outcomes
• Implement monitoring and alerting mechanisms for abnormal conditions

These practices enable faster issue resolution and reduce dependency on external support.

Moving Forward

This chapter is organized into detailed sections covering:

• The structure of SPG transaction meta information
• The functional meaning and usage rules of key response fields
• The complete set of transaction states and their operational interpretation
• A state transition model, including asynchronous flows, exceptions, and reversals
• A unified catalogue of transaction status codes and error codes
• Error payload examples and recommended handling strategies
• A troubleshooting guide covering common scenarios and resolution actions

Each section builds on the concepts introduced here and provides the necessary detail to support implementation, operation, and debugging of SPG integrations.

By understanding how SPG represents and communicates transaction information, merchants can ensure robust, predictable, and scalable payment integrations.

Summary

This chapter defines the semantic contract between SPG and the merchant system, establishing the mandatory rules for interpreting transaction data, state evolution, and operational outcomes.

It enables merchants to consistently:

• Deterministic interpretation of transaction outcomes
• Correct implementation of payment flows and state transitions
• Robust handling of asynchronous and error scenarios
• Reduced integration errors and operational overhead

All integrators should use this chapter as the authoritative reference for interpreting SPG responses across all payment methods and integration models.