Production-ready integrations must be designed to operate correctly under asynchronous and event-driven conditions, where transaction outcomes are not immediate and evolve over time.

In SIBS Payment Gateway (SPG) integrations, several payment methods depend on user interaction or external systems, resulting in delayed or non-deterministic transaction finalization. A system that assumes immediate finality will produce incorrect outcomes, inconsistent states, or premature business actions.

Asynchronous-First Execution Model

SPG integrations must adopt an asynchronous-first mindset, treating all transaction outcomes as potentially delayed.

A typical transaction lifecycle may include:

• Initial API request and response
• Intermediate state (e.g., Pending)
• Final outcome determined after external interaction or asynchronous processing

As a result:

• Initial responses must not be interpreted as final outcomes
• Systems must support state evolution over time
• Business actions must be deferred until the final state is confirmed

Pending must be treated as a first-class state, explicitly supported in both system logic and reconciliation processes.

See F.3 – Success and Error Scenarios for the transaction state model and interpretation framework.

Event-Driven State Propagation

Asynchronous flows rely on event-driven updates to propagate transaction state changes.

Webhook notifications provide:

• Near real-time updates of state transitions
• Event triggers for internal processing

However, webhook delivery is not guaranteed to be:

• Single (duplicates may occur)
• Ordered (events may arrive out of sequence)
• Immediate (delays may occur)

Repeated delivery attempts and webhook replay behavior may also occur during temporary failures or uncertain delivery conditions.

A production-ready system must:

• Process webhook events in an idempotent and order-independent manner
• Use events as triggers for processing workflows, after validation and correlation with the known transaction context
• Ensure that event handling does not introduce inconsistent or conflicting transaction states

See E.1 – Webhooks (Notifications) for notification delivery behavior.

Transaction-State Resolution

Figure – Asynchronous Transaction Lifecycle and Transaction-State Resolution

Final transaction state must be determined from validated final paymentStatus data, or through Status Inquiry when confirmation, recovery, or reconciliation is required.

In SPG integrations:

• Webhooks provide event-driven updates
• Status Inquiry provides the latest transaction state available through the query API when confirmation or reconciliation is required

Inquiry Details responses may provide extended transaction context and historical processing information useful for investigation, reconciliation, and validation of complex asynchronous flows.

A correct implementation:

• Uses webhooks to trigger processing
• Confirms final state when required via the Status Inquiry
• Ensures consistency between event-driven updates, internal transaction state, and Status Inquiry results when used for confirmation or reconciliation

This model reflects an eventual consistency approach, where temporary discrepancies between systems may occur.

Differences between webhook notifications, Status Inquiry responses, Inquiry Details responses, and internal Merchant system state must therefore be reconciled using controlled consistency validation mechanisms.

See F.6 – Production Readiness Guidelines for the consistency model and F.3 – Success and Error Scenarios for interpretation rules.

Handling Delayed and Uncertain Outcomes

Asynchronous flows introduce scenarios where the final outcome is not immediately known.

These include:

• Pending states awaiting user action
• Timeouts or indeterminate outcomes
• Delayed confirmation from external systems

A production-ready system must:

• Explicitly support non-final states
• Avoid premature success or failure assumptions
• Implement follow-up mechanisms (e.g., status validation) when required

This includes explicit handling of timeout scenarios where the final outcome must be actively resolved.

Production-ready integrations are responsible for ensuring that unresolved or indeterminate transaction states are eventually reconciled to a definitive outcome.

Failure to handle these scenarios correctly may result in:

• Incorrect order fulfillment
• Customer-facing inconsistencies
• Reconciliation issues

Temporary error conditions (statusCode = Txxxx) may contribute to delayed or uncertain outcomes and must be handled through controlled retry strategies rather than immediate failure assumptions.

Consistency Across Asynchronous Stages

Transaction consistency must be preserved across all stages of the asynchronous lifecycle.

This includes:

• Initial request processing
• Webhook-driven updates
• Status Inquiry / Get Status confirmation when required

Because state may evolve over time:

• Later events must not override a valid final state
• State transitions must remain valid and controlled
• Systems must prevent regression (e.g., Success → Pending)

Consistency must be maintained even when events are delayed, duplicated, or received out of order.

See F.6.2 – Transaction Idempotency and Duplicate Protection for idempotent handling requirements.

Operational Readiness for Asynchronous Behavior

Production environments introduce variability that must be handled explicitly.

A production-ready integration must:

• Tolerate delays in user interaction and external processing
• Handle repeated and out-of-order events safely
• Maintain consistent state under retry and failure scenarios
• Provide operational visibility into delayed processing, unresolved transactions, repeated events, retries, and asynchronous reconciliation activities
• Ensure that all transaction outcomes are eventually resolved and reconciled
• Final transaction-state validation must rely on validated final paymentStatus data, or on Status Inquiry when confirmation, recovery, or reconciliation is required

Asynchronous readiness is not optional – it is a fundamental requirement for correct behavior in SPG integrations.

See F.5 – Logging and Monitoring Best Practices for observability, monitoring, traceability, and operational diagnostics guidance.

Final Consideration

Asynchronous processing is intrinsic to SPG payment flows.

A production-ready system ensures that:

• Transaction state is treated as evolving over time
• Events are processed reliably and idempotently
• Final outcomes are confirmed through validated final paymentStatus data, or through Status Inquiry when required
• Business actions are aligned with confirmed transaction states

Systems that assume synchronous behavior in an asynchronous environment will inevitably produce incorrect outcomes, even if the underlying API integration is technically correct.