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

The structure and mapping of API-level status codes are defined in C.5.1 API-Level Status Codes.

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

Error Representation Model

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

• synchronous API responses
• webhook notifications
• Status Inquiry responses

Error Code Interpretation Strategy

Error handling in SPG must follow a structured interpretation model combining:

• HTTP status code
• returnStatus.statusCode
• paymentStatus

These three elements must be interpreted together to correctly classify the outcome and determine the appropriate handling strategy.

Interpretation Layers

The interpretation model is composed of three distinct layers, each with a specific responsibility:

The following model defines the evaluation order and priority of these layers:

Figure – Error Interpretation Layer Model

These layers must be evaluated together. No single field is sufficient to determine the final outcome.

For the complete interpretation model of statusCode, statusMsg, and paymentStatus, refer to C.5 – Status Codes and Error Codes Mapping.

Interpretation hierarchy:

1. paymentStatus → defines the business outcome (authoritative)
2. returnStatus.statusCode → refines the technical classification
3. returnStatus.statusMsg → provides high-level categorization (informational)

statusDescription must not be used for any decision-making logic.

Examples:

• T9999 → temporary condition → retry with backoff
• E0101 → invalid request → fix payload before retry
• E0119 → declined operation → do not retry automatically
• 10.106.0001 → business decline → user-driven retry only

This interpretation model must be applied consistently across all API responses, webhook notifications, and status inquiry operations.

Operational Decision Model

The statusCode must be interpreted according to its category:

This classification must be consistently applied across API responses, webhooks, and status inquiries.

Important

HTTP status codes must be used only to detect transport-level failures (e.g., network errors, invalid endpoints, authentication issues).

A successful HTTP response (e.g., HTTP 200) indicates only successful transport, not a successful business outcome. Business outcome must always be determined using paymentStatus.

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

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

Detailed operational error codes are defined in C.5.3 Legacy / Detailed Error Codes.

statusMsg

• high-level classification:
  • Success
  • Pending
  • Declined
  • Error
• 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 the following categories:

1. Validation Errors

Characteristics

• invalid or malformed request
• missing or incorrect parameters
• configuration issues

Typical Indicators

• statusCode = Exxxx (inspect specific code and documented guidance)
• paymentStatus = Error

Examples

• invalid request payload
• missing required fields

2. Business Errors (Declined Operations)

Characteristics

• operation processed successfully
• rejected at business level

Typical Indicators

• paymentStatus = Declined
• statusMsg = Declined

Examples

• insufficient funds
• user rejection
• authentication failure

3. 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

4. Temporary Errors

Characteristics

• transient system or network condition
• operation may succeed if retried

Typical Indicators

• statusCode = Txxxx
• paymentStatus = Error

Examples

• temporary system unavailability
• network issues
• external dependency failure

5. Conflict / State Errors

Characteristics

• operation conflicts with current transaction state
• duplicate or invalid lifecycle operation

Typical Indicators

• specific E01xx codes indicating state conflict

Examples

• transaction already processed
• duplicate operation
• invalid state transition

6. Timeout / Abandonment

Characteristics

• operation not completed within expected time window
• 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"
}

This represents an operational error code and must be interpreted together with API-level statusCode and paymentStatus.

Handling Strategy

Error handling must follow a layered interpretation model:

1. Evaluate paymentStatus to determine the business outcome
2. Refine the classification using returnStatus.statusCode
3. Use HTTP status only to detect transport-level failures

All three layers must be considered before applying any retry, failure handling, or user interaction logic.

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 only if the error is identified as a temporary condition (statusCode = Txxxx)

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
• statusCode indicates a temporary condition (Txxxx)
• the operation is idempotent

Temporary errors (Txxxx) must be retried using controlled retry mechanisms with exponential backoff.

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 <ROOT_URL>/payments/{transactionID}/status

Important

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

Use Status Inquiry when explicit verification or recovery is required, especially when webhook delivery or processing is uncertain.

 

Valid final-state webhooks must be processed idempotently and must not be treated as secondary to Status Inquiry by default.

Operational Rules

Rule 1 – Use paymentStatus as primary indicator

• defines business outcome

Rule 2 – Use statusCode for technical classification

• defines technical nature of result

Rule 2.1 – Apply statusCode category semantics

• Txxxx codes must be treated as retryable conditions
• Exxxx codes must be evaluated according to the specific error code and documented handling guidance
• Business decline codes must not trigger automatic retries

Rule 3 – Do not use statusDescription for decision logic

• use only for diagnostics

Rule 4 – Handle all final states explicitly

• Success
• Declined
• Error
• Timeout

Rule 5 – Reconcile before final action when required

• confirm final transaction state using Status Inquiry when explicit verification or recovery is required

Implementation Checklist

Merchant systems must:

• classify errors correctly (validation, business, technical, temporary, conflict/state, 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