Overview

A critical integration pitfall in SIBS Payment Gateway (SPG) implementations is the inadequate interpretation and handling of error conditions and transaction outcomes.

This occurs when integrators:

• misinterpret response fields
• conflate technical and business outcomes
• or apply simplistic success/failure logic

In SPG, transaction responses contain multiple layers of meaning, and correct behavior depends on interpreting them accurately within the transaction lifecycle. Misinterpretation leads to incorrect system decisions and inconsistent business outcomes.

Nature of Error Interpretation in SPG

SPG responses typically include distinct indicators that must be interpreted independently:

• returnStatus
  → represents the technical processing result of the request
• paymentStatus
  → represents the business outcome or current state of the transaction

These two dimensions are not equivalent.

A technically successful response does not necessarily indicate a successful payment outcome, and a non-final payment state does not necessarily indicate an error.

Correct interpretation requires understanding the relationship between these dimensions.

The Core Pitfall

The core issue arises when integrations assume:

“If the request was successful, the payment was successful.”

or conversely:

“If the payment is not successful, the request failed.”

Both assumptions are incorrect.

Typical misinterpretations include:

• Treating returnStatus.statusCode = "000" as confirmation of payment success
• Treating non-final states (e.g., Pending) as failures
• Treating declined payments as technical errors
• Ignoring the distinction between processing errors and business outcomes

These mistakes collapse distinct concepts into a single success/failure model.

Incorrect Implementation Patterns

Inadequate error interpretation typically manifests as:

• Triggering business success actions based solely on returnStatus
• Failing to act on paymentStatus changes
• Misclassifying declined payments as system errors
• Not distinguishing between temporary states and final outcomes
• Applying uniform error handling across all scenarios
• Ignoring contextual information when evaluating transaction results

These patterns result in incorrect decision-making and inconsistent system behavior.

Correct Interpretation Model

A correct implementation must treat SPG responses as multi-dimensional signals, where:

• Technical processing (returnStatus)
  → confirms whether the request was correctly received and processed
• Business outcome (paymentStatus)
  → defines the current transaction state within its lifecycle

Both dimensions must be evaluated independently and in context.

This requires:

• Basing business decisions on paymentStatus, not returnStatus
• Recognizing intermediate states as part of normal processing
• Distinguishing between:
  • technical failures (e.g., invalid request)
  • business outcomes (e.g., declined payment)

As defined in F.3 Success and Error Scenarios, correct interpretation depends on understanding the meaning of each status within the transaction lifecycle.

Relationship with Transaction Lifecycle

Error interpretation is directly tied to lifecycle management.

Because transaction states evolve over time:

• a response may reflect an intermediate state
• final outcomes may be delivered asynchronously
• multiple updates may occur before completion

Incorrect interpretation leads to:

• premature decisions
• incorrect state transitions
• inconsistent system behavior

A correct implementation must interpret responses in the context of ongoing state evolution, not as isolated events.

Relationship with Asynchronous Processing

Asynchronous behavior increases the complexity of error interpretation.

For example:

• a transaction may initially return a successful technical response but remain in Pending
• a webhook may later indicate a final outcome
• multiple status updates may occur over time

A correct implementation must:

• avoid interpreting intermediate states as errors
• handle delayed outcomes appropriately
• ensure that final decisions are based on authoritative state

Failure to do so leads to incorrect conclusions about transaction success or failure.

Consequences of Inadequate Error Handling

Improper interpretation and handling of errors leads to:

• incorrect confirmation or rejection of transactions
• misclassification of valid declines as system failures
• premature cancellation of valid transactions
• inconsistent transaction state across systems
• incorrect user communication
• increased reconciliation complexity

These issues directly impact both system reliability and user trust.

Key Principle

SPG responses must be interpreted as multi-dimensional and state-dependent signals, not as simple success/failure indicators.

Correct integration behavior requires:

• separating technical processing results from business outcomes
• interpreting transaction states within their lifecycle context
• handling intermediate and final states appropriately

Any integration that reduces SPG responses to a single success/failure dimension will produce incorrect, inconsistent, and unreliable behavior in production environments.