Overview

All SIBS Payment Gateway (SPG) interactions must be interpreted using a dual-layer model, separating technical processing outcomes from business transaction outcomes.

This distinction is fundamental to ensure that integrators:

• Avoid incorrect assumptions based on API responses
• Prevent premature business actions (e.g., order fulfillment)
• Maintain consistent transaction state management across all payment methods

The complete interpretation model and code definitions are described in C.5 – Status Codes and Error Codes Mapping.

Technical Outcome

The technical outcome reflects whether the request was successfully received, validated, and processed at the API level.

It is determined by:

• HTTP Status Code
  • Indicates transport-level success or failure (e.g., 200, 400, 401)
• returnStatus object
  • statusCode
  • statusMsg

A typical successful technical response is:

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    }
}

Interpretation

• statusCode = "000" indicates that the request was successfully processed at technical level and does not guarantee a successful payment.
• Any other code (e.g., E0xxx) indicates that the request did not complete successfully at technical level, although in some cases partial processing may still have occurred.

Key Characteristics

• Evaluated immediately upon API response
• Independent from payment method behavior
• Does not guarantee that a transaction was executed or completed

Business Outcome

The business outcome reflects the actual result of the payment transaction.

It is determined by:

• paymentStatus field

Typical values include:

• Success → Payment completed successfully
• Pending → Awaiting user action or external processing
• Declined → Payment refused
• Error → Processing failure
• Timeout → Final transaction outcome not determined within expected timeframe

Interpretation

• Defines the financial and operational state of the transaction
• May evolve over time (e.g., Pending → Success)
• Final paymentStatus must be used to drive business decisions and workflows

The returnStatus layer reflects the API processing result and does not independently determine the final business outcome of the transaction. Business interpretation must consider paymentStatus as the transaction outcome indicator when present in final webhook or Status Inquiry responses.

Combined Interpretation

Both layers must be evaluated together when paymentStatus is present.

Example 1 – Technical Success, Business Success

{
    "returnStatus": { "statusCode": "000" },
    "paymentStatus": "Success"
}

→ Payment completed successfully

Example 2 – Technical Success, Business Pending

{
    "returnStatus": { "statusCode": "000" },
    "paymentStatus": "Pending"
}

→ Payment not finalized; further action required

Example 3 – Technical Success, Business Declined

{
    "returnStatus": { "statusCode": "000" },
    "paymentStatus": "Declined"
}

→ Payment refused despite valid request

Example 4 – Technical Failure

{
    "returnStatus": { "statusCode": "E0101" }
}

→ Request rejected or not successfully completed at technical level

Key Rule

A technically successful response (statusCode = "000") does not imply a successful payment.

This rule must be strictly enforced in all integrations.

State Evolution and Timing

The technical outcome is instantaneous, while the business outcome may evolve over time.

Typical pattern:

• Initial response:
  • statusCode = "000"
  • paymentStatus = "Pending"
• Final state (via webhook or Status Inquiry):
  • paymentStatus = "Success" or Declined

This behavior is especially common in:

• MB WAY
• Multibanco Reference
• Card payments with 3DS
• Two-step flows (AUTH → CAPTURE)

Integrator Responsibilities

To correctly implement this model, integrators must:

• Evaluate both returnStatus and paymentStatus when paymentStatus is present
• Treat Pending as a valid and expected state
• Base business actions on final paymentStatus
• Use the Status Inquiry (GET <ROOT_URL>/payments/{transactionID}/status) to confirm final outcomes when required
• Ensure internal systems support state transitions over time

For extended transaction diagnostics and additional contextual information, refer to E.2 – Status Inquiry / Get Status.

Common Anti-Patterns (To Avoid)

• Treating statusCode = "000" as payment success
• Ignoring paymentStatus in initial responses
• Assuming synchronous completion for all payment methods
• Triggering fulfillment actions while transaction is still Pending
• Failing to reconcile final state after asynchronous flows

Summary

The separation between technical outcome and business outcome is a core principle of SPG integrations.

• The technical layer confirms that the request was processed
• The business layer defines the actual transaction result

Correct implementation of this model ensures:

• Accurate transaction state management
• Proper handling of asynchronous flows
• Consistent and reliable business operations