Overview
Production readiness in SIBS Payment Gateway (SPG) integrations is defined by the ability of the system to operate correctly, consistently, and predictably under real-world conditions, not only under controlled or ideal scenarios.
In practice, payment processing involves:
- Asynchronous and delayed outcomes
- External system dependencies
- Non-deterministic timing of final states
- Retry, duplication, and reconciliation scenarios
A technically correct implementation that does not account for these conditions will result in inconsistent transaction states, operational instability, or financial discrepancies.
This section defines the minimum operational guarantees that an integration must enforce to ensure reliable behavior in production.
Error classification and handling behavior must follow the model defined in C.5 – Status Codes and Error Codes Mapping and C.6 – Error Payloads and Handling Guidelines.
Operational Reality of SPG Integrations
Figure – Production Readiness and Transaction Lifecycle Control
SPG integrations operate under a model where transaction outcomes are not always immediate or singular.
A single payment interaction may involve:
- An initial API response indicating successful processing at technical level
- A pending state requiring user action or external confirmation
- A final outcome delivered asynchronously
As a result:
- A successful API response does not imply a successful payment
- Payment state must be observed over time
- Multiple signals must be correlated to determine the final outcome
This behavior is intrinsic to several payment methods and flows, including those requiring user interaction or deferred settlement.
Production environments may also involve transactions initiated through multiple operational channels or platforms, requiring consistent reconciliation and lifecycle management across heterogeneous transaction origins.
A production-ready system must therefore treat transaction state as evolving, not static.
This behavior is further detailed in F.3 – Success and Error Scenarios and illustrated in F.1 – End-to-End Integration Examples.
Deterministic Control of Transactions
Each transaction must be handled as a uniquely identifiable and controlled entity across its entire lifecycle.
This requires:
- Consistent use of identifiers such as
transactionIDandmerchant.merchantTransactionId - Protection against duplicate submissions and unintended retries
- Explicit control over transaction state transitions
Without deterministic control:
- Duplicate payments may be triggered
- Valid operations may be rejected as duplicates
- Transaction history becomes unreliable
Production systems must guarantee that each operation is processed exactly once at business level, even if executed multiple times at transport level.
Asynchronous and Event-Driven Behavior
SPG integrations must be designed with an asynchronous-first mindset.
Transaction outcomes may depend on:
- Customer interaction (e.g., approval flows)
- External systems (e.g., payment networks)
- Delayed processing steps
The typical execution pattern includes:
- Initial request and response
- Intermediate state (e.g., Pending)
- Final state delivered asynchronously
This requires:
- Continuous state tracking
- Event-driven processing
- Explicit handling of delayed finalization
Systems that assume immediate finality will produce incorrect business outcomes.
Webhook delivery behavior, asynchronous notification semantics, and transaction state validation mechanisms are further detailed in E.1 – Webhooks (Notifications) and E.2 – Status Inquiry / Get Status.
Transaction-State Consistency and Reconciliation
Transaction state must be determined from validated transaction data and reconciled when asynchronous, delayed, or inconsistent signals are received.
In SPG integrations:
- Webhooks provide near real-time updates
- Status Inquiry provides the latest transaction state available through the query API when confirmation or reconciliation is required
These mechanisms operate under an eventual consistency model, where temporary discrepancies may exist between different sources of information.
Differences between webhook notifications, Status Inquiry responses, Inquiry Details responses, and internal Merchant system state must therefore be reconciled using controlled consistency validation strategies.
A correct implementation:
- Uses webhooks as triggers
- Confirms final state when required
- Maintains internal consistency despite timing differences
Inquiry Details responses may provide extended transaction context and historical processing information useful for reconciliation, operational diagnostics, and investigation of complex transaction flows.
See F.3 – Success and Error Scenarios for the interpretation model and F.1 – End-to-End Integration Examples for practical validation patterns.
Resilience Under Failure Conditions
Production environments introduce failure scenarios that do not occur in controlled testing:
- Network interruptions
- Partial request execution
- Timeouts with unknown outcomes
- Repeated delivery of the same event
The integration must remain correct under these conditions by:
- Applying controlled retry strategies
- Avoiding duplicate processing
- Preserving transaction state integrity
Failures must not lead to inconsistent or irreversible system states.
Retry behavior must be based on error classification: temporary conditions (statusCode = Txxxx) may be retried using a retry with backoff strategy, while validation or business errors (statusCode = Exxxx) must not be retried automatically.
Reliable Event Processing
Event handling, particularly for asynchronous notifications, must be:
- Idempotent
- Order-independent
- Safe under repeated delivery
Notifications may:
- Be delivered multiple times
- Arrive out of order
- Be delayed relative to the actual transaction state
Webhook delivery retries and repeated asynchronous notifications must be treated as expected operational behavior and processed using duplicate-safe and idempotent handling strategies.
The system must process them in a way that guarantees consistent final outcomes regardless of delivery behavior, including duplicate, delayed, or out-of-order notifications.
See E.1 – Webhooks (Notifications) for notification structure and delivery behavior.
End-to-End Consistency and Reconciliation
A production-ready integration ensures that transaction state remains consistent across:
- SPG platform
- Merchant system
- Customer-facing flows
This requires:
- Alignment between API responses, events, and internal state
- Explicit reconciliation mechanisms
- Protection against invalid state transitions
Consistency must be maintained even when information is received at different times or through different channels.
Observability and Traceability
All transactions must be fully traceable across their lifecycle.
It must be possible to:
- Correlate API requests with resulting events
- Track the evolution of transaction state
- Identify and diagnose failures
This level of visibility is required to operate and support the integration in production conditions.
See F.5 – Logging, Monitoring, and Observability for implementation guidelines.
Data Integrity and Financial Accuracy
All transaction data must remain consistent and verifiable across systems.
This includes:
- Exact preservation of monetary values
- Consistent identifiers and timestamps
- Validation of message integrity where applicable
Any inconsistency directly impacts reconciliation and financial correctness.
See C.2 – Field Semantics and Validation Rules for field-level constraints and validation requirements.
Final Consideration
Production readiness is achieved when the integration behaves correctly under:
- Delayed outcomes
- Repeated events
- Partial failures
- External system dependencies
Most production issues in SPG integrations arise not from incorrect API usage, but from:
- Incorrect assumptions about transaction finality
- Inadequate handling of asynchronous flows
- Lack of idempotency and state control
A production-ready system is one that guarantees correct outcomes under uncertainty, not only under ideal execution conditions.