Overview

A critical integration pitfall in SIBS Payment Gateway (SPG) implementations is the use of blocking or synchronous processing patterns in inherently asynchronous flows.

This occurs when integrations attempt to:

• wait for immediate completion of operations
• perform long-running processing within synchronous request/response cycles
• or enforce linear execution in a non-linear, event-driven model

In SPG, many transaction flows are asynchronous by design, and attempting to impose synchronous behavior leads to instability, timeouts, and inconsistent system behavior.

Nature of the Problem

SPG transaction processing involves multiple asynchronous elements:

• external user interaction (e.g., MB WAY approval)
• delayed state transitions
• webhook-based event delivery
• eventual consistency between systems

These characteristics mean that:

• transaction completion cannot be guaranteed within a single request
• processing must be decoupled across time and system components

Blocking execution while waiting for these events fundamentally contradicts the operational model of the platform.

The Core Pitfall

The core issue arises when integrations assume:

“The system should wait until the transaction is completed before proceeding.”

This assumption leads to designs where:

• API calls are expected to return final outcomes
• application threads are blocked while waiting for external events
• webhook processing includes synchronous dependencies

This is incompatible with SPG’s asynchronous model.

Incorrect Implementation Patterns

Blocking or synchronous processing typically manifests as:

• Waiting for payment completion within the initial API request cycle
• Holding user sessions or threads open while awaiting transaction finality
• Performing long-running business logic inside webhook request handlers
• Calling SPG APIs synchronously within webhook processing before responding
• Chaining multiple dependent operations in a single synchronous flow
• Treating asynchronous events as part of a linear execution path

These patterns introduce tight coupling between otherwise independent stages of the transaction lifecycle.

Correct Processing Model

A correct implementation must adopt a non-blocking, event-driven approach, where:

• API calls initiate operations without expecting immediate finality
• application flows proceed based on available information, not future outcomes
• webhook notifications trigger asynchronous processing
• long-running or dependent operations are decoupled from request/response cycles

Processing must be structured such that:

• each step completes independently
• subsequent actions are triggered by events or state changes
• no component depends on the immediate completion of external processes

As demonstrated in F.1 End-to-End Integration Examples, correct behavior emerges from coordinating independent steps rather than enforcing synchronous execution.

Relationship with Webhook Processing

Blocking behavior is particularly problematic in webhook handling.

Webhook endpoints are expected to:

• receive notifications
• acknowledge them promptly
• delegate processing asynchronously

Improper implementations often:

• perform full business processing before responding
• call external systems synchronously
• delay acknowledgment while executing complex logic

This leads to:

• timeouts
• repeated webhook delivery
• duplicate processing

As defined in E.1 Webhooks, webhook processing must remain lightweight and non-blocking.

Relationship with Asynchronous and Event-Driven Design

SPG integrations must operate under an event-driven model, where:

• state changes are communicated asynchronously
• processing is triggered by events rather than direct calls
• system components operate independently

Blocking behavior introduces:

• artificial coupling
• reduced system resilience
• inability to handle timing variability

Correct design requires embracing:

• eventual consistency
• decoupled processing
• asynchronous execution patterns

Consequences of Blocking Behavior

Using blocking or synchronous patterns in asynchronous flows leads to:

• request timeouts and degraded performance
• repeated webhook deliveries due to delayed acknowledgment
• duplicate processing and inconsistent state
• poor scalability under load
• inability to handle real-world delays and variability
• fragile systems that fail under production conditions

These issues are amplified in payment systems, where timing and reliability are critical.

Key Principle

Asynchronous flows must be handled with non-blocking, event-driven processing.

Correct integration behavior requires:

• decoupling processing steps across the transaction lifecycle
• avoiding synchronous waiting for external outcomes
• ensuring that all components operate independently and respond promptly

Any integration that attempts to enforce synchronous behavior in asynchronous flows will produce unstable, inefficient, and unreliable systems in production environments.