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

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.

Status Code Model

Structure

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

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

Status Code Categories

SPG status codes can be grouped into the following categories:

1. Success Codes

Example

000

Meaning

• Operation successfully processed by SPG

Important Rule

statusCode = "000" does not guarantee payment success

Example

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

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

Status Code vs paymentStatus

Critical Rule

statusCode and paymentStatus must always be interpreted together.

Mapping Principle

Important Observations

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

Therefore, paymentStatus is the authoritative business indicator.

statusMsg Semantics

Purpose

Provides a high-level classification of the operation result.

Typical Values

• Success
• Pending
• Declined
• Error
• InProcessing

Rules

• Must not be used as the sole decision driver
• 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
  • InProcessing

Rule 4 – Use statusDescription for diagnostics only

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

Rule 5 – Reconcile using Status API

• Webhooks and API responses may differ
• Always confirm using:

GET https://spg.qly.site1.sibs.pt/api/v2/payments/{transactionID}/status

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

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
• Reconcile using status API 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 model must be consistently applied across all SPG integrations and payment methods.