Overview

One of the most common and critical integration pitfalls in SIBS Payment Gateway (SPG) implementations is the incorrect assumption regarding payment finality.

This occurs when integrators assume that the immediate response returned by an API call represents the final outcome of the transaction.

In reality, SPG operates under an asynchronous and state-based model, where:

• initial responses indicate technical processing status
• transaction outcomes may evolve over time
• final states are often reached only after external interaction or asynchronous processing

Failure to correctly distinguish between technical response and final business outcome leads to incorrect system behavior and financial inconsistencies.

The Core Misinterpretation

A typical incorrect assumption is:

“If the API response is successful, the payment is completed.”

This assumption is invalid in SPG integrations.

A response such as the following:

• HTTP 200
• returnStatus.statusCode = "000"

only confirms that the request was successfully received and processed at a technical level.

It does not confirm:

• that the payment was authorized
• that funds were captured
• that the transaction reached a final state

As defined in F.3 – Success and Error Scenarios, the technical result (returnStatus) and the business outcome (paymentStatus) are independent and must be interpreted separately.

The final transaction state must be determined from validated final paymentStatus data, or through Status Inquiry / Get Status when confirmation, recovery, or reconciliation is required, as described in E.1 – Webhooks (Notifications) and E.2 – Status Inquiry / Get Status.

Asynchronous Nature of Payment Flows

Many SPG payment methods and flows are inherently asynchronous, including:

• MB WAY (user approval via mobile device)
• Multibanco Reference (offline payment completion)
• Card payments involving authentication steps (e.g., 3DS)
• Two-step payment models (AUTH followed by CAPTURE)

In these scenarios, the transaction lifecycle typically follows:

1. Initial API request and response
2. Intermediate state (e.g., Pending)
3. External interaction or processing
4. Final state transition (Success, Declined, or another final paymentStatus)

Intermediate states such as Pending must not be interpreted as either successful or failed outcomes and require continued lifecycle monitoring until a definitive final state is reached.

This behavior is fundamental to the SPG model and must be explicitly supported by the integration, as reinforced in F.6 – Production Readiness Guidelines.

Incorrect Implementation Patterns

Misinterpreting payment finality commonly leads to the following implementation errors:

• Treating the initial API response as the final transaction outcome
• Ignoring or bypassing asynchronous updates
• Updating business systems (e.g., order confirmation) prematurely
• Not supporting intermediate states such as Pending
• Failing to re-evaluate transaction state after the initial response

These patterns result from applying a synchronous mindset to an inherently asynchronous system.

Correct Interpretation Model

A correct implementation must treat payment processing as a multi-step, evolving process, where no single signal is sufficient to determine the final outcome.

Specifically:

• API responses
  → indicate immediate technical processing
• Webhook notifications
  → provide event-driven updates on state transitions
• Status Inquiry / Get Status
  → confirmation of transaction state when required
• Inquiry Details
  → extended transaction visibility and operation-level diagnostics when required

As demonstrated in F.1 – End-to-End Integration Examples, these components must be used together to correctly determine transaction outcomes.

Extended transaction visibility and lifecycle diagnostics may additionally require the use of Inquiry Details, as described in E.2.10 – Inquiry Details API.

Status Inquiry / Get Status must be used when the Merchant system needs to confirm or reconcile transaction state, particularly in scenarios involving delays, retries, or uncertainty.

Consequences of Misinterpretation

When payment finality is misinterpreted, the resulting issues are systemic and high-impact:

• Orders confirmed without successful payment
• Delivery of goods or services without funds settlement
• Inconsistent transaction records across systems
• Increased reconciliation effort and financial risk
• Incorrect user communication (false success or failure messages)

These issues are difficult to detect in controlled environments and typically surface only under real-world conditions.

Key Principle

Payment finality in SPG must never be inferred from a single interaction.

Final transaction outcome must be determined through:

• state evolution over time
• correlation of multiple signals
• validation against confirmed transaction-state data

Any implementation that assumes immediate finality from synchronous responses will produce incorrect and unreliable results in production environments.