Overview

This section provides a practical troubleshooting framework for diagnosing and resolving issues when integrating with the SIBS Payment Gateway (SPG).

It focuses on:

• identifying common failure scenarios
• mapping symptoms to root causes
• defining corrective actions
• ensuring consistent and safe recovery

The objective is to enable merchant systems and operators to:

• quickly diagnose integration issues
• avoid incorrect business decisions
• maintain operational continuity

This section complements the reconciliation model defined in C.7 – State Reconciliation: Query vs Webhook.

Troubleshooting Approach

All troubleshooting must follow a structured diagnostic process.

Step 1 – Identify Transaction

Collect:

• transactionID
• merchantTransactionId

Step 2 – Retrieve Current State

GET /api/v2/payments/{transactionID}/status

Step 3 – Inspect Key Fields

Analyze:

• paymentStatus
• returnStatus.statusCode
• returnStatus.statusMsg
• returnStatus.statusDescription

Step 4 – Classify Issue

Determine whether the issue is:

• business (Declined)
• technical (Error)
• timeout / abandonment

Step 5 – Apply Corrective Action

Use the scenarios below to determine next steps.

Common Scenarios and Resolution

1. Payment Stuck in Pending

Symptoms

• paymentStatus = Pending for extended period
• no final state received

Possible Causes

• user did not complete authorization (e.g., MB WAY)
• webhook not received
• external system delay

Actions

• query Status API repeatedly
• verify webhook configuration
• implement polling fallback
• allow the user to retry the transaction

2. Payment Timeout

Symptoms

• paymentStatus = Timeout
• statusDescription indicates abandonment

Possible Causes

• user inactivity
• session expiration

Actions

• treat as incomplete transaction
• allow the user to retry the transaction
• do not assume decline

3. Payment Declined

Symptoms

• paymentStatus = Declined
• statusCode indicates business rejection

Possible Causes

• insufficient funds
• authentication failure
• user rejection

Actions

• inform user
• allow retry with different method
• do not retry automatically

4. Technical Error During Processing

Symptoms

• paymentStatus = Error
• statusCode indicates technical issue

Possible Causes

• malformed request
• network failure
• downstream system issue

Actions

• log full payload
• retry if error is transient
• validate request format

5. Webhook Not Received

Symptoms

• no webhook received
• transaction remains unresolved

Possible Causes

• webhook endpoint unavailable
• incorrect configuration
• network issues

Actions

• verify endpoint availability
• check webhook configuration in Backoffice
• rely on Status API polling

6. Duplicate Webhooks

Symptoms

• same notification received multiple times

Possible Causes

• webhook retry mechanism

Actions

• implement idempotent processing
• ignore duplicates

7. Out-of-Order Webhooks

Symptoms

• state appears to regress (e.g., Success → Pending)

Possible Causes

• asynchronous delivery
• retry mechanism

Actions

• enforce monotonic state progression
• ignore backward transitions
• validate with Status API

8. Status API vs Webhook Inconsistency

Symptoms

• webhook state differs from Status API

Possible Causes

• delayed webhook
• out-of-order delivery

Actions

• trust Status API
• re-query after delay
• treat webhook as event trigger only

9. statusCode = "000" but Payment Not Successful

Symptoms

• statusCode = "000"
• paymentStatus ≠ Success

Possible Causes

• operation technically successful
• business flow not completed

Actions

• rely on paymentStatus
• do not assume success

10. Duplicate Transactions

Symptoms

• multiple transactions for same business operation

Possible Causes

• retry without idempotency
• repeated API calls

Actions

• enforce idempotency
• ensure unique merchantTransactionId
• validate before retry

Diagnostic Decision Matrix

Key Diagnostic Rules

Rule 1 – paymentStatus is the source of truth

• defines business outcome

Rule 2 – statusCode refines interpretation

• provides error classification

Rule 3 – statusDescription is diagnostic only

• never use for logic

Rule 4 – Always use Status API for confirmation

• avoid relying solely on webhooks

Rule 5 – Never act on non-final states

• Pending
• InProcessing

Preventive Best Practices

1. Implement Idempotency

• avoid duplicate transactions
• ensure safe retries

2. Use Both Webhooks and Polling

• combine event-driven and polling strategies

3. Log All Transactions

• ensure full traceability

4. Handle All Final States Explicitly

• Success
• Declined
• Error
• Timeout

5. Validate Integration Regularly

• test webhook delivery
• validate status reconciliation

Implementation Checklist

Merchant systems must:

• implement structured troubleshooting process
• classify errors correctly
• use Status API for validation
• handle all scenarios described above
• ensure idempotent processing
• maintain detailed logs
• support retry and recovery mechanisms

Summary

SPG integrations operate in a distributed and asynchronous environment, where issues may arise due to:

• user behavior
• system failures
• network conditions
• integration errors

A structured troubleshooting approach ensures:

• fast diagnosis of issues
• correct interpretation of transaction state
• safe and predictable recovery
• robust and reliable payment processing