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

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 by the platform
• 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 → Outcome not determined within expected timeframe

Interpretation

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

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.

Combined Interpretation

Both layers must always be evaluated together.

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; no valid transaction outcome

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 API):
  • 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:

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

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