Overview

One of the most common and critical integration pitfalls in SIBS Payment Gateway (SPG) implementations is the misinterpretation of 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.

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, Timeout)

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 API
  → provides authoritative confirmation of the final transaction state

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

The Status API must be considered the authoritative source when confirming the final 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 an authoritative source

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