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 and approval 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
• Omnichannel operations
  → may introduce channel-dependent operational timing
  → may involve asynchronous refund or reconciliation behavior
  → require lifecycle consistency across physical and digital channels

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

Different payment methods may also expose distinct intermediate states, transition sequences, authorization semantics, settlement timing, expiration behavior, and post-processing requirements. Integrations must therefore avoid assuming that state progression, completion timing, or operational transitions are identical across all payment methods.

See D.1 – One-Off Payments, D.2 – Recurring Payments, D.3 – Two-Step Payments, and D.4 – Omnichannel Operations for detailed payment method operational behavior and lifecycle semantics.

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, retry, or reconciliation logic across all payment methods
• Assuming all payments reach final state within the same timeframe
• Applying identical user experience and operational flows regardless of payment method behavior
• 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 and approval 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.

Behavioral Timing and Lifecycle Variability

Payment method differences are closely tied to asynchronous behavior.

For example:

• Card payments may exhibit near real-time behavior but can still involve asynchronous lifecycle transitions and authentication steps (e.g., 3DS)
• MB WAY introduces explicit user-driven delays
• Multibanco introduces extended asynchronous completion windows

A correct implementation must therefore:

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

Transaction-state validation and reconciliation across different payment methods must rely on E.2 – Status Inquiry / Get Status rather than assumptions based on timing expectations.

Event-driven integrations should also incorporate E.1 – Webhooks (Notifications) to handle asynchronous state propagation consistently across payment methods with different execution timelines.

When extended operational diagnostics are required, additional lifecycle visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API.

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.