Overview

This section defines how error scenarios are represented, interpreted, and handled in the SIBS Payment Gateway (SPG).

It covers:

• structure of error payloads
• classification of error types
• interpretation of returnStatus fields
• recommended handling strategies
• retry and recovery patterns

The objective is to ensure that merchant systems:

• correctly distinguish between technical and business failures
• implement safe and deterministic error handling
• maintain resilience in asynchronous and distributed environments

Error Representation Model

Errors in SPG are represented through the returnStatus object, which is present in:

• synchronous API responses
• webhook notifications
• status API responses

Structure of returnStatus

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

Field Semantics

statusCode

• machine-readable classification of the outcome
• used for technical interpretation and categorization

statusMsg

• high-level classification:
  • Success
  • Pending
  • Declined
  • Error
  • InProcessing
• provides a coarse-grained indication of the result

statusDescription

• human-readable explanation
• provides detailed context of the outcome

Examples

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

Error Classification

Errors must be classified into three main categories:

1. Business Errors (Declines)

Characteristics

• operation processed successfully
• rejected at business level

Typical Indicators

• paymentStatus = Declined
• statusMsg = Declined

Examples

• insufficient funds
• user rejection
• authentication failure

2. Technical Errors

Characteristics

• failure during processing
• system or integration issue

Typical Indicators

• paymentStatus = Error
• statusMsg = Error

Examples

• invalid request format
• downstream system failure
• communication issues

3. Timeout / Abandonment

Characteristics

• operation not completed in time
• no explicit success or decline

Typical Indicators

• paymentStatus = Timeout
• statusMsg = Pending or Timeout

Examples

• user did not approve MB WAY request
• session expired

Error Payload Examples

Example 1 – Business Decline

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

Example 2 – Timeout / Abandonment

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

Example 3 – Technical Error

{
    "returnStatus": {
        "statusMsg": "Error",
        "statusCode": "12.110.1903",
        "statusDescription": "SIBS Internal error. Please try again later."
    },
    "paymentStatus": "Error"
}

Handling Strategy

Error handling must be based on paymentStatus first, then refined using statusCode.

statusCode = "000" does not guarantee a successful payment.

The final business outcome must always be determined using paymentStatus.

1. Business Errors (Declined)

Action

• do not retry automatically
• allow user to retry manually
• provide user feedback

Do Not

• treat as technical failure
• trigger automatic retries

2. Technical Errors

Action

• log error details
• evaluate retry strategy
• retry if transient

Retry Guidelines

• apply exponential backoff
• ensure idempotency
• limit retry attempts

3. Timeout / Abandonment

Action

• treat as incomplete transaction
• allow user to restart flow

Important

• do not assume decline
• do not assume success

Retry Strategy

Retries must be controlled and safe.

When to Retry

Retry only when:

• paymentStatus = Error
• error is identified as transient (e.g., temporary system, network, or downstream dependency issue)

When NOT to Retry

Do not retry when:

• paymentStatus = Declined
• paymentStatus = Success
• paymentStatus = Timeout

Retry Requirements

• idempotent operations
• unique merchantTransactionId handling
• proper logging and traceability

Idempotency and Duplicate Handling

Merchant systems must ensure:

• repeated operations do not create duplicate transactions
• retries are safely handled
• webhook events are processed idempotently

Logging and Observability

All error scenarios must be logged with:

• transactionID
• merchantTransactionId
• full returnStatus object
• timestamp
• operation context

paymentStatus must be explicitly logged

Reconciliation Rule

Error interpretation must always be confirmed via:

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

Important

• webhook errors may reflect intermediate states
• API responses may not be final

Always validate the final state via Status API

Operational Rules

Rule 1 – Use paymentStatus as primary indicator

• defines business outcome

Rule 2 – Use statusCode for classification

• defines technical nature of result

Rule 3 – Do not use statusDescription for logic

• use only for diagnostics

Rule 4 – Handle all final states explicitly

• Success
• Declined
• Error
• Timeout

Rule 5 – Always reconcile before final action

• confirm final state using Status API

Implementation Checklist

Merchant systems must:

• classify errors correctly (business vs technical vs timeout)
• implement retry logic only for technical errors
• ensure idempotent processing
• log all error payloads
• reconcile final state before business actions
• provide clear user feedback for failures

Summary

SPG error handling is based on a structured and deterministic model, where:

• returnStatus provides detailed error context
• paymentStatus defines the actual outcome
• different error categories require different handling strategies

Correct implementation ensures:

• robust and resilient integrations
• correct handling of all failure scenarios
• prevention of incorrect retries or duplicate processing
• consistent and predictable payment processing behavior