Overview

This chapter addresses the most frequent integration pitfalls observed in SIBS Payment Gateway (SPG) implementations, focusing on the gap between technically correct integrations and systems that behave reliably in real-world conditions.

In SPG, correctness is not determined solely by:

• successful API calls
• valid payload structures
• proper authentication

but by the ability of the integration to produce consistent and validated transaction outcomes under asynchronous, non-deterministic conditions.

As established in F.6 – Production Readiness Guidelines, production environments introduce characteristics that fundamentally impact payment processing:

• delayed and evolving transaction states
• external dependencies and user interaction
• retries, duplication, and partial failures

An integration that does not explicitly account for these conditions will inevitably exhibit inconsistencies, even if all API interactions are formally correct.

Scope and Positioning

This chapter does not redefine transaction flows, payload structures, or state models. Those aspects are defined elsewhere in the documentation.

Instead, the focus here is on incorrect assumptions and flawed implementation patterns that lead to:

• premature business decisions
• inconsistent transaction states
• reconciliation discrepancies
• operational instability

The purpose is therefore diagnostic and corrective:

• to highlight where integrations typically fail
• to explain why those failures occur
• to align implementation behavior with the SPG operational model

This chapter intentionally avoids redefining implementation architectures, operational controls, or transaction lifecycle models, focusing instead on the misapplication or misinterpretation of those principles in real integrations.

Integration Reality vs Implementation Assumptions

A recurring source of failure in SPG integrations is the mismatch between how integrators expect the system to behave and how it actually operates.

In practice, a single payment interaction may involve:

• an initial API response indicating successful technical processing
• an intermediate state requiring external confirmation
• a final outcome delivered asynchronously

This behavior is intrinsic to the platform and must be treated as such, as emphasized in F.6 – Production Readiness Guidelines.

A critical implication follows:

As further detailed in F.3 – Success and Error Scenarios, transaction outcomes must be interpreted across multiple dimensions, including technical processing status and business outcome, which are independent and may evolve over time.

Pitfalls emerge when implementations collapse these distinctions and act on incomplete or intermediate signals.

The final transaction state must be determined from validated final paymentStatus data, or through Status Inquiry / Get Status when confirmation, recovery, or reconciliation is required, as defined in:

• E.1 – Webhooks (Notifications)
• E.2 – Status Inquiry / Get Status
• F.3 – Success and Error Scenarios
• C.6 – Error Payloads and Handling Guidelines

The Nature of Pitfalls in SPG Integrations

Unlike simple API integrations, SPG requires systems to operate correctly across:

• multiple interaction mechanisms (API, webhook notifications, Status Inquiry, Inquiry Details)
• multiple timeframes (immediate and delayed)
• multiple sources of information (event-driven notifications and query-based validation)

This introduces inherent complexity:

• events may be delayed, duplicated, or out of order
• transaction states may change after the initial response
• timeout scenarios represent uncertain operational outcomes and must not be interpreted as final payment failure without validation
• different system components may temporarily reflect inconsistent states

As demonstrated in F.1 – End-to-End Integration Examples, correct behavior depends on combining:

• immediate responses for flow continuation
• webhook notifications for event-driven updates
• Status Inquiry / Get Status confirmation when required

Pitfalls occur when any of these elements is not correctly handled:

• ignored
• over-relied upon
• incorrectly interpreted

The following simplified flow illustrates common operational points where incorrect assumptions, missing validation, or weak asynchronous handling typically introduce integration inconsistencies.

Root Cause of Most Integration Failures

Across real-world implementations, most issues can be traced back to a small set of conceptual errors:

• Treating transactions as instantaneous instead of lifecycle-based
• Assuming deterministic behavior in a non-deterministic system
• Failing to correctly correlate events and state transitions across the transaction lifecycle, including failure to enforce idempotent processing and correct use of transaction identifiers such as transactionID and merchant.merchantTransactionId
• Designing systems with a synchronous mindset in an asynchronous model

These errors are not visible at development time in controlled environments but emerge under:

• real user behavior
• network variability
• production load
• asynchronous execution timing

This is why, as highlighted in F.6 – Production Readiness Guidelines, production readiness is defined by behavior under uncertainty – not by correctness under ideal conditions.

Operational Consequences

When these pitfalls are present, the resulting operational issues are systemic rather than isolated and typically propagate across payment processing, reconciliation, fulfillment, customer support, and financial reporting processes:

• orders confirmed before payment completion
• duplicate or inconsistent transactions
• incorrect handling of retries and failures
• inability to reconcile transaction states
• lack of traceability across systems

Over time, these inconsistencies frequently propagate into customer support issues, reconciliation complexity, operational overhead, and financial reporting discrepancies.

These are not edge cases – they are predictable outcomes of incorrect integration assumptions.

Retries must be explicitly controlled and applied only to temporary conditions (statusCode = Txxxx), using a retry with backoff strategy and idempotency protection mechanisms as defined in F.6.2 – Idempotency and Duplicate Protection and C.6 – Error Payloads and Handling Guidelines.

Without proper observability, as emphasized in F.5 – Logging and Monitoring Best Practices, such issues may remain undetected or misinterpreted, further amplifying operational risk.

Final Consideration

The primary objective of this chapter is to shift the integration mindset from:

“The API works correctly”

to:

“The system behaves correctly under real-world conditions”

SPG integrations must be designed with the understanding that:

• payment processing operates under an eventual consistency model
• transaction state is not immediate and not singular
• multiple signals must be correlated to determine the final transaction state
• correctness depends on handling uncertainty, not avoiding it

Integrations that fail to internalize these principles will exhibit systemic inconsistencies in production, regardless of technical correctness at API level.

Correct integration behavior depends on consistent application of the interpretation model (see C.5 – Status Codes and Error Codes Mapping), handling strategies (see C.6 – Error Payloads and Handling Guidelines), and scenario-based processing patterns described in F.3 – Success and Error Scenarios.