Overview

This section defines the meaning, classification, and usage of status codes returned by the SIBS Payment Gateway (SPG).

SPG responses include a returnStatus object with:

• statusCode → machine-readable code
• statusMsg → high-level classification
• statusDescription → human-readable explanation

These elements must always be interpreted together with:

• paymentStatus

This section establishes:

• how status codes are structured
• how they must be interpreted
• how they relate to paymentStatus
• how merchant systems must react to them

The objective is to ensure consistent, deterministic, and safe handling of all SPG outcomes.

SPG defines multiple code domains depending on operation type and payment method (e.g., checkout, payment request, status inquiry, MB WAY, Multibanco, Card, and security contexts). These domains follow different structures but are interpreted using the same principles defined in this section. The detailed structure and mapping of these domains are addressed in the subsequent sections of this chapter.

The interpretation rules defined in this section must be applied in conjunction with the semantic model described in C.2 – Field Semantics and Validation Rules.

Status Code Model Structure

Key Principles

• statusCode represents the technical outcome of the operation.
• It must be interpreted together with:
  • statusMsg
  • paymentStatus
• It does not independently determine the business result

Structure

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

It does not independently determine the business result.

Different code families may be used depending on the operation context (e.g., API-level responses, operational error domains, or payment-method-specific errors), but this interpretation rule remains consistent across all cases (see C.5.1 – API-Level Status Codes, C.5.2 – Error Code Categories and Responsibility Model, C.5.3 – Legacy / Detailed Error Codes, and C.5.4 – Payment Method-Specific Error Domains).

Status Code Categories

SPG status codes can be grouped into the following categories:

1. Success Codes

Important Rule

statusCode = "000" + paymentStatus = Pending → valid
statusCode = "000" + paymentStatus = Declined → valid

statusCode = "000" indicates successful technical processing, but does not guarantee a successful business outcome.

2. Pending / Processing Codes

Examples

• 00.110.1601

Meaning

• Operation accepted but not finalized
• Awaiting external confirmation or completion

Typical Usage

• asynchronous flows
• MB WAY approval
• external authorization steps

3. Declined Codes

Examples

• 10.106.0001

Meaning

• Operation completed but rejected at business level

Typical Causes

• insufficient funds
• authentication failure
• user rejection

4. Error Codes

Meaning

• Technical failure during processing

Typical Causes

• system errors
• communication failures
• invalid request structure

5. Timeout / Abandonment Codes

Examples

• 00.110.1601

Meaning

• Operation not completed within allowed time

Typical Causes

• user inactivity
• session expiration
• external system timeout

These categories represent a conceptual grouping of outcomes. The same statusCode may appear in different contexts depending on the transaction state and payment method. Detailed mappings are provided in the subsequent sections of this chapter.

Status Code vs paymentStatus

Critical Rule

statusCode and paymentStatus must always be interpreted together.

For the operational meaning of each paymentStatus value, refer to C.3 – Transaction States and Operational Meaning.

Mapping Principle

To clarify the interpretation hierarchy between these elements, the following model applies:

Figure – Interpretation Priority Model

Important Observations

• statusCode = "000" may appear in:
  • final success
  • intermediate states
  • even declined scenarios

Therefore, paymentStatus is the only authoritative indicator of the transaction’s business outcome.

statusMsg Semantics

Purpose

Provides a high-level classification of the operation result.

Typical Values

• Success
• Pending
• Declined
• Error

Rules

• Must not be used for any decision logic
• May not reflect final state accurately

statusDescription Usage

Purpose

Provides detailed contextual explanation of the outcome.

Examples

• Success
• Card holder abandoned the transaction (push notification not accepted nor refused)
• After the operation was successful, was refused by the cardholder
• Issue with the Operation (declined)

Rules

• Must be treated as free text
• Must not be used for:
  • business logic
  • conditional branching
• Should be used for:
  • logging
  • debugging
  • support analysis
  • operational visibility

Operational Interpretation Rules

Rule 1 – Always prioritize paymentStatus

paymentStatus > statusMsg > statusCode

Rule 2 – Do not assume success from statusCode

statusCode = "000" does not guarantee success

Rule 3 – Validate finality using paymentStatus

• Only act when:
  • paymentStatus is final
• Never act on:
  • Pending

Rule 4 – Use statusDescription for diagnostics only

• Never use for logic
• Use for:
  • logs
  • support tickets
  • troubleshooting

Rule 5 – Use Status Inquiry When Required

• The Status Inquiry API retrieves the current transaction state:

GET <ROOT URL>/payments/{transactionID}/status

Use it when explicit verification or recovery is required, especially when webhook delivery or processing is uncertain. Do not present Status Inquiry as automatically overriding a valid final-state webhook.

For a complete reconciliation strategy across asynchronous flows, refer to C.7 – State Reconciliation: Query vs Webhook.

Examples

Example 1 – Successful Transaction

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

Example 2 – Pending Transaction

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000",
        "statusDescription": "Success"
    },
    "paymentStatus": "Pending"
}

Example 3 – Declined Transaction

{
    "returnStatus": {
        "statusMsg": "Declined",
        "statusCode": "10.106.0001",
        "statusDescription": "After the operation was successful, was refused by the cardholder."
    },
    "paymentStatus": "Declined"
}

Example 4 – Abandoned Transaction

{
    "returnStatus": {
        "statusMsg": "Pending",
        "statusCode": "00.110.1601",
        "statusDescription": "Card holder abandoned the transaction (push notification not accepted nor refused)"
    },
    "paymentStatus": "Timeout"
}

Error Handling Strategy

Technical Errors

• paymentStatus = Error
• Action:
  • retry if transient
  • log and escalate if persistent

Business Failures

• paymentStatus = Declined
• Action:
  • do not retry automatically
  • allow user retry

Timeouts

• paymentStatus = Timeout
• Action:
  • restart flow
  • allow user retry

Different handling strategies may apply depending on the specific code domain and payment method see C.5.2 – Error Code Categories and Responsibility Model, C.5.3 – Legacy / Detailed Error Codes, and C.5.4 – Payment Method-Specific Error Domains).

Implementation Checklist

Merchant systems must:

• Always evaluate paymentStatus first
• Use statusCode for technical validation only
• Never rely on statusMsg alone
• Never use statusDescription for logic
• Handle asynchronous flows properly
• Use Status Inquiry for verification or recovery when needed
• Log all status components for traceability

Summary

SPG status codes provide a technical classification of operation results, but must always be interpreted in conjunction with paymentStatus, which defines the actual business outcome.

Correct implementation ensures:

• accurate handling of all transaction outcomes
• proper distinction between technical and business results
• resilience to asynchronous behavior and edge cases
• robust and predictable payment processing logic

This interpretation model applies across all SPG operations and payment methods, regardless of the specific code domain used.