Overview

A recurring integration pitfall in SIBS Payment Gateway (SPG) implementations is the assumption that all payment methods behave in a uniform manner.

This occurs when integrators design a single, generic processing model and apply it across different payment methods without accounting for their distinct behavioral characteristics.

In SPG, each payment method has specific:

• execution patterns
• timing characteristics
• user interaction requirements
• lifecycle semantics

Ignoring these differences leads to incorrect assumptions, inconsistent handling, and unreliable transaction processing.

Nature of Payment Method Variability

SPG supports multiple payment methods, each with its own operational behavior.

Examples include:

• Card payments
  → typically immediate or near real-time processing
  → may involve authentication steps (e.g., 3DS)
  → support both single-step and two-step flows (AUTH → CAPTURE)
• MB WAY
  → requires user approval via mobile device
  → introduces asynchronous delays
  → may involve mandate-based flows for recurring scenarios
• Multibanco Reference
  → fully asynchronous and offline
  → requires external payment completion
  → introduces extended validity and delayed confirmation

These differences are not superficial – they directly affect how transactions must be handled throughout their lifecycle.

The Core Pitfall

The core issue arises when integrations assume:

“All payment methods follow the same execution model.”

This leads to:

• applying synchronous logic to asynchronous methods
• expecting uniform timing and behavior
• ignoring method-specific lifecycle requirements

Such assumptions result in incorrect system behavior when real transaction flows diverge from the generic model.

Incorrect Implementation Patterns

Ignoring payment method-specific behavior typically manifests as:

• Treating asynchronous methods (e.g., MB WAY, Multibanco) as if they were immediate
• Applying identical timeout or retry logic across all payment methods
• Assuming all payments reach final state within the same timeframe
• Using the same user experience flow regardless of payment method
• Not handling method-specific states or transitions
• Ignoring method-specific post-processing requirements

These patterns result from overgeneralization and lack of method-aware design.

Correct Handling Approach

A correct integration must treat each payment method as having its own behavioral model, while maintaining a consistent overall architecture.

This requires:

• Understanding the execution characteristics of each payment method
• Adapting processing logic to account for:
  • timing differences
  • user interaction requirements
  • lifecycle variations
• Ensuring that system behavior aligns with:
  • how each payment method actually operates
  • not how a generic model assumes it should operate

While core concepts (e.g., transaction states, correlation, idempotency) remain consistent, their application must be adapted to each method.

Relationship with Asynchronous Processing

Payment method differences are closely tied to asynchronous behavior.

For example:

• Card payments may appear synchronous but can still involve asynchronous steps (e.g., authentication)
• MB WAY introduces explicit user-driven delays
• Multibanco introduces extended asynchronous completion windows

A correct implementation must therefore:

• handle each method’s asynchronous characteristics appropriately
• avoid assuming uniform timing or behavior
• design systems that remain consistent across varying execution patterns

Consequences of Ignoring Method Differences

Failure to account for payment method-specific behavior leads to:

• incorrect assumptions about transaction timing and finality
• premature confirmation or cancellation of transactions
• inconsistent user experience across payment methods
• improper handling of state transitions
• failed or incomplete transaction processing
• increased reconciliation complexity

These issues become more pronounced as integrations scale across multiple payment methods.

Key Principle

Payment methods in SPG must be treated as behaviorally distinct, even within a unified integration model.

Correct integration behavior requires:

• recognizing and respecting method-specific execution patterns
• adapting processing logic to match real-world behavior
• avoiding overgeneralization across different payment methods

Any integration that assumes uniform behavior across payment methods will produce inconsistent, incorrect, and unreliable outcomes in production environments.