Overview

This section describes the different error patterns that may occur in SIBS Payment Gateway (SPG) integrations.

Errors must be interpreted using the dual-layer model:

• Technical layer → returnStatus.statusCode
• Business layer → paymentStatus (when applicable)

The combination of these fields determines:

• Whether a transaction exists
• Whether it was processed
• What action the integrator must take

Technical Errors (Request Rejected)

Description

Errors where the request is invalid and rejected before processing.

Example (Invalid Request / Missing Data)

{
  "returnStatus": {
    "statusCode": "E0101",
    "statusMsg": "Error",
    "statusDescription": "Invalid request, data is missing or is invalid"
  }
}

Interpretation

• Request not processed
• No transaction created
• No paymentStatus

Integrator Action

• Validate request payload:
  • Mandatory fields
  • Amount and currency
  • Terminal configuration (e.g., terminalId = 12345)
• Do not retry without correction

Business Errors (Declined Transactions)

Description

Errors where:

• Request is valid
• Transaction is created
• Payment is refused

Example (Insufficient Funds)

{
  "paymentStatus": "Declined",
  "returnStatus": {
    "statusCode": "E0113",
    "statusMsg": "Error",
    "statusDescription": "Insufficient funds"
  },
  "transactionID": "tx_A1B2C3D4"
}

Interpretation

• Transaction exists
• Payment failed at business level
• Cause defined by returnStatus.statusDescription

Integrator Action

• Inform the user
• Allow retry with:
  • Different payment method
  • Different credentials
• Do not retry automatically

Duplicate / Conflict Errors

Description

Errors caused by duplicate submission or conflicting requests.

Example

{
  "returnStatus": {
    "statusCode": "E0127",
    "statusMsg": "Error",
    "statusDescription": "Transaction already made"
  }
}

Interpretation

• Transaction already exists
• Request rejected to prevent duplication

Integrator Action

• Retrieve transaction via Status API
• Ensure unique merchantTransactionId
• Implement idempotency

Temporary Errors (Retryable)

Description

Errors caused by temporary system conditions.

Example

{
  "returnStatus": {
    "statusCode": "T9999",
    "statusMsg": "Temporary error",
    "statusDescription": "SIBS temporary internal error"
  }
}

Interpretation

• Request not completed
• Final outcome may be unknown

Integrator Action

• Retry using exponential backoff
• If uncertainty remains:
  • Confirm via Status API
• Include in reconciliation

Authentication and Authorization Errors

Description

Errors occurring at the security layer.

Example

{
  "returnStatus": {
    "statusCode": "E0900",
    "statusMsg": "Error",
    "statusDescription": "Invalid authentication or authorisation data"
  }
}

Interpretation

• Request rejected before processing
• Invalid or missing credentials

Integrator Action

• Validate:
  • Authorization headers
  • Client credentials
• Regenerate credentials if needed
• Do not retry blindly

Payment Method-Specific Errors

Description

Errors specific to payment method validation and processing rules.

Card Example (Invalid Card Data)

{
  "paymentStatus": "Declined",
  "returnStatus": {
    "statusCode": "E0700",
    "statusMsg": "Error",
    "statusDescription": "Invalid card data"
  }
}

MB WAY Example (Invalid Alias)

{
  "paymentStatus": "Declined",
  "returnStatus": {
    "statusCode": "E0503",
    "statusMsg": "Error",
    "statusDescription": "The provided alias is not correct"
  }
}

Multibanco Example (Invalid Currency)

{
  "returnStatus": {
    "statusCode": "E0603",
    "statusMsg": "Error",
    "statusDescription": "Invalid currency"
  }
}

Interpretation

• Error depends on payment method constraints
• May occur at validation or processing stage

Integrator Action

• Apply method-specific validation
• Provide clear user feedback
• Avoid generic retry logic

Key Error Handling Rules

• Always evaluate:
  • returnStatus.statusCode
  • paymentStatus (when present)
• Always:
  • Use returnStatus.statusDescription for diagnostics
  • Use Status API when outcome is unclear
• Never:
  • Retry without classification
  • Treat all errors as retryable
  • Assume Declined is a technical failure

Summary

Error handling requires explicit classification and deterministic response strategies.

Each error category implies a different handling approach:

• Validation errors → fix request
• Business declines → user action
• Temporary errors → retry
• Security errors → correct credentials

Correct handling ensures:

• Consistent transaction state management
• Controlled retry behavior
• Reliable production operation