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 completion. 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)

A production-ready system must:

• Process webhook events in an idempotent and order-independent manner
• Use events as triggers for processing, not as the authoritative source of truth
• Ensure that event handling does not introduce inconsistent or conflicting transaction states

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

Authoritative State Resolution

Final transaction state must always be derived from authoritative sources, not inferred from intermediate signals.

In SPG integrations:

• Webhooks provide event-driven updates
• The Status API provides authoritative confirmation of the final transaction state

A correct implementation:

• Uses webhooks to trigger processing
• Confirms final state when required via the Status API
• Ensures consistency between event-driven updates and the authoritative state returned by the Status API

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

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.

Failure to handle these scenarios correctly may result in:

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

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 API validation

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
• Ensure that all transaction outcomes are eventually resolved and reconciled

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

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 authoritative sources
• 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.