Overview

This chapter consolidates the key cross-cutting principles and consistency rules that apply across all sections of Chapter F. Technical Examples and Best Practices and the broader SPG documentation.

Its purpose is to ensure that integrators interpret examples, flows, and behaviors consistently across different integration models, payment methods, and operational scenarios, avoiding misinterpretation caused by isolated reading of individual sections of the documentation.

Event vs Transaction-State Confirmation

Across all examples and flows in this documentation, a strict distinction must be maintained between:

• Event-driven signals (e.g., webhook notifications)
• Confirmed transaction-state outcome, obtained from a validated final webhook payload or from Status Inquiry / Get Status when confirmation, reconciliation, recovery, or inconsistency resolution is required

Webhook notifications represent asynchronous state transitions or processing events. In some scenarios, they may carry a final paymentStatus; however, transaction-state confirmation and reconciliation must follow the applicable validation rules.

When confirmation, reconciliation, recovery, or inconsistency resolution is required, the transaction state should be confirmed using Status Inquiry / Get Status:

GET /payments/{transactionID}/status

This principle is consistently applied in:

• F.3 – Success and Error Scenarios
• F.10.1 – Webhook Reception, Decryption and Processing Flow
• F.10.3 – End-to-End Webhook Processing Scenario

Asynchronous Processing Model

All payment methods and flows must be interpreted within a distributed asynchronous processing model, even when operations appear synchronous.

This implies:

• responses to API calls may not represent final state
• webhook notifications may arrive after delays
• transaction completion may depend on external interaction

This model is consistently reflected across:

• F.1 – End-to-End Examples
• F.6 – Production Readiness Guidelines
• F.10 – Webhook Integration Examples

Idempotency as a Core Requirement

Idempotency is a mandatory requirement across all processing flows.

All examples assume:

• webhook notifications may be delivered multiple times
• operations must be safe under repetition
• notificationID is used as the idempotency and deduplication key for webhook notification processing.
• transactionID remains the primary transaction correlation identifier across the transaction lifecycle

This principle applies to:

• webhook processing (F.10.1 – Webhook Reception, Decryption and Processing Flow, F.10.5 – Failure Handling, Retries and Idempotency)
• retry handling (F.6 – Production Readiness Guidelines, F.7 – Common Integration Pitfalls, F.10.5 – Failure Handling, Retries and Idempotency)
• system state updates

Separation of Acknowledgement and Processing

Webhook acknowledgement must be treated as a technical delivery confirmation, independent from business processing.

Across all relevant sections:

• acknowledgement must be immediate
• acknowledgement must not depend on processing success
• processing must be asynchronous

This model is defined and reinforced in:

• F.10.2 – Webhook Acknowledgement Handling
• F.10.5 – Failure Handling, Retries and Idempotency

Retry and Failure Handling Model

Retry behavior must always be interpreted as part of the asynchronous delivery mechanism, not as a business signal.

Across all examples:

• retries may result in duplicate notifications
• delivery order is not guaranteed
• failures must be handled internally

Additionally:

• SPG retry behavior is independent from merchant logic
• failure visibility is provided through Backoffice-configured notifications

This model is described in:

• F.6 – Operational Resilience and Failure Strategy
• F.7 – Common Integration Pitfalls
• F.10.5 – Failure Handling, Retries and Idempotency

Payment Method Abstraction

While payment methods differ in behavior, all examples follow a common abstraction model:

• consistent transaction identification (transactionID)
• consistent webhook structure
• consistent transaction-state lifecycle

Differences between payment methods (e.g., CARD, MBWAY, REFERENCE) affect:

• timing
• user interaction
• intermediate states

But do not change:

• core processing principles
• idempotency requirements
• state validation rules

This abstraction is maintained across:

• F.1 – End-to-End Examples
• F.2 – Requests and Responses
• F.10.4 – Payment Method-Specific Webhook Examples

Status Inquiry / Get Status for Reconciliation

Status Inquiry / Get Status must be treated as the reconciliation and confirmation mechanism when the merchant needs to verify, recover, or resolve the transaction state.

All examples assume:

• validated webhook data may represent a transaction-state event, including final-state notifications in applicable scenarios
• Status Inquiry / Get Status is used when additional confirmation or reconciliation is required
• final internal decisions must rely on a validated transaction-state source: either a validated final webhook notification or Status Inquiry / Get Status when required
• discrepancies must be resolved through Status Inquiry / Get Status validation when reconciliation is required

This principle is consistently applied in:

• F.3 – Success and Error Scenarios
• F.6 – Data Integrity and Consistency Controls
• F.10.3 – End-to-End Webhook Processing Scenario

When extended operational diagnostics are required during reconciliation analysis, troubleshooting, or lifecycle investigation, additional visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API.

Consistency Across Integration Models

The principles described in this chapter apply equally to:

• Form Integration
• Server-to-Server Integration
• Plugin-based integrations

While implementation details differ, the following remain constant:

• transaction lifecycle model
• asynchronous behavior
• webhook processing requirements
• status reconciliation model

This ensures that all integration approaches remain functionally consistent.

Operational Responsibility Boundaries

Across all chapters, responsibilities are clearly separated:

• SPG responsibilities:
  • transaction processing
  • webhook delivery
  • retry mechanisms
• Merchant responsibilities:
  • webhook endpoint availability
  • acknowledgement handling
  • idempotent processing
  • internal retry logic
  • transaction state validation

Understanding these boundaries is critical for correct system design and troubleshooting.

Final Consideration

All examples, flows, and patterns in Chapter F are designed to be interpreted within a unified processing model, where:

• events are asynchronous
• transaction-state outcomes must be validated before they are persisted or reconciled internally
• processing must be idempotent and resilient

By applying these consistency rules across all chapters, integrators ensure that their implementation remains:

• correct across all payment methods
• resilient under failure conditions
• aligned with SPG operational behavior

This guarantees a coherent, reliable, and production-ready integration, independent of specific use cases or implementation details.