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 at business level, 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 merchant.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.

Operation-Level Idempotency

Idempotency must be enforced consistently across all transaction operations, including purchase (PURS) and authorization (AUTH) flows, as well as Merchant-Initiated Transaction (MIT) and recurring-payment scenarios.

For each operation:

• A unique merchant.merchantTransactionId must be used to identify the transaction attempt
• Reuse of the same identifier may result in duplicate suppression or reuse of the original transaction
• SIBS SPG may return the original transaction instead of creating a new one

Idempotency must be applied uniformly regardless of payment method or integration model.

Purchase and Authorization Idempotency

In purchase (PURS) and authorization (AUTH) flows, idempotency ensures that repeated submission of the same logical operation does not result in multiple financial effects.

Key principles:

• Each request must use a unique merchant.merchantTransactionId representing a single logical operation
• Repeated requests with the same identifier may return the original transaction result
• Duplicate purchase attempts must not result in multiple charges
• Duplicate authorization attempts must not create multiple holds on customer funds

For two-step flows, idempotency must be preserved across both AUTH and CAPTURE phases, ensuring that repeated capture attempts do not result in multiple settlements for the same authorization.

Repeated CAPTURE requests following uncertain outcomes or timeout conditions must be validated carefully against the current validated transaction state before re-execution to prevent duplicate settlement.

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 Suppression Behavior

SIBS SPG may implement duplicate detection based on merchant.merchantTransactionId and transaction context.

Possible behaviors include:

• Returning the original transaction result for repeated requests
• Rejecting the request as a duplicate operation
• Preventing creation of a new transaction

Integrators must not assume that duplicate requests will be processed independently.

Duplicate handling behavior is not guaranteed to be deterministic. Integrators must not rely on a specific outcome (e.g. reuse vs rejection) and must design systems to handle all possible duplicate response scenarios.

Duplicate Event Handling (Webhooks)

Figure – Idempotent Processing and Duplicate Protection Lifecycle

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

Webhook replay handling must preserve reconciliation consistency and prevent repeated downstream business processing.

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 Inquiry / Get Status confirmation when required
• Inquiry Details responses for extended transaction investigation and reconciliation analysis

See F.6 – Production Readiness Guidelines for transaction-state consistency and reconciliation 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
• Final transaction validation must rely on validated final paymentStatus data, or on Status Inquiry when confirmation, recovery, or reconciliation is required.
• Temporary discrepancies may exist between webhook notifications, Status Inquiry responses, Inquiry Details responses, and internal transaction state during asynchronous processing windows

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

All retries, duplicate detections, suppression decisions, and reprocessing outcomes should be logged and correlated to support operational traceability and investigation.

Improper retry strategies may lead to:

• Duplicate transactions
• Conflicting states
• Operational instability

Retries must only be applied when the outcome is uncertain due to temporary conditions (statusCode = Txxxx). Validation or business errors (statusCode = Exxxx) must not trigger retries and require correction or user-driven resolution.

Retries must always reuse the same merchant.merchantTransactionId when representing the same logical operation. Generating new identifiers during retries may result in duplicate transactions and inconsistent system state.

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.

For error classification and retry decision models, refer to C.6 – Error Payloads and Handling Guidelines and F.2.7 – Error Scenarios and Edge Cases.