Production-ready integrations must ensure that all payment operations are protected against duplication and unintended reprocessing, regardless of how many times a request or event is received or reprocessed.

In real-world conditions, retries, network instability, and asynchronous processing may cause the same operation to be executed multiple times at transport level due to retries or network-level uncertainty. Without proper controls, this can result in duplicated transactions, inconsistent states, or financial discrepancies.

Idempotency as a Core Requirement

Idempotency ensures that repeated execution of the same logical operation produces a single, consistent outcome.

In SPG integrations, idempotency must be enforced at business level, not only at API level.

This means:

• A payment operation must be processed exactly once in intent, even if triggered multiple times
• Repeated requests must not create additional financial transactions
• System behavior must remain consistent under retries, replays, and duplicate events

Failure to enforce idempotency may result in:

• Duplicate charges
• Rejected transactions due to duplication rules
• Inconsistent reconciliation between systems

Use of Unique Transaction Identifiers

Each transaction must be uniquely identified and consistently correlated across all stages of its lifecycle.

This requires:

• A unique merchantTransactionId for each logical operation
• Consistent use of transactionID returned by SPG for all subsequent interactions

These identifiers must be:

• Persisted reliably
• Reused for correlation across API calls, webhook processing, and status validation

Improper handling of identifiers is a primary cause of duplication issues and reconciliation failures.

Duplicate Request Handling

Duplicate requests may occur due to:

• Client-side retries (e.g., user actions, UI resubmissions)
• Server-side retry mechanisms
• Network timeouts with unknown outcomes

A production-ready system must:

• Detect duplicate requests based on transaction identifiers
• Prevent re-execution of already processed operations
• Return consistent responses for repeated requests

Retry mechanisms must be:

• Controlled and conditional
• Aware of previous execution outcomes
• Designed to avoid creating new transactions unintentionally

Duplicate Event Handling (Webhooks)

Asynchronous notifications must also be treated as potentially duplicated events.

Webhook delivery may involve:

• Multiple deliveries of the same notification
• Delayed or out-of-order arrival

The system must:

• Process each notification in an idempotent manner
• Use notificationID (or equivalent identifier) to prevent duplicate processing
• Ensure that repeated notifications do not alter the final transaction state

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

Interaction with Asynchronous Flows

Idempotency must be maintained across the full transaction lifecycle, including asynchronous stages.

This includes:

• Initial request execution
• Webhook-triggered updates
• Status API validation

See F.6 Production Readiness Guidelines for the authoritative state model and consistency principles.

Because transaction state evolves over time:

• Repeated actions must not override or regress a valid final transaction state.
• State transitions must remain consistent and controlled

See F.3 Success and Error Scenarios for transaction state interpretation and handling.

Retry Strategy and Safe Reprocessing

Retries are necessary in production environments but must be applied safely.

A correct retry strategy:

• Retries only when the outcome is unknown or uncertain
• Avoids retrying operations that are already completed or definitively failed
• Uses transaction identifiers and current transaction state to determine whether reprocessing is safe

Improper retry strategies may lead to:

• Duplicate transactions
• Conflicting states
• Operational instability

Consistency Across Systems

Idempotency must ensure consistent behavior across:

• SPG platform
• Merchant system
• External components involved in the flow

This requires:

• Alignment of identifiers and state tracking
• Protection against conflicting updates
• Deterministic handling of repeated operations

Consistency must be preserved even when operations are executed multiple times or events are delivered repeatedly.

Final Consideration

Idempotency and duplicate protection are fundamental to financial correctness.

In SPG integrations, duplication risks arise naturally from:

• Retries
• Asynchronous processing
• Distributed system behavior

A production-ready integration ensures that:

• Each logical operation produces a single outcome
• Duplicate requests and events are safely handled
• Transaction state remains consistent across all systems

Without these guarantees, even correctly implemented integrations may result in duplicated payments, rejected operations, or reconciliation issues.