Overview

A critical integration pitfall in SIBS Payment Gateway (SPG) implementations is the improper handling of retries and duplicate events.

This occurs when integrations fail to correctly manage repeated requests or repeated notifications, which are inherent in distributed and asynchronous systems. As a result, systems may process the same logical transaction multiple times, leading to inconsistent state and incorrect business outcomes.

In SPG, retries and duplicates are expected behaviors, not exceptional conditions. A robust integration must therefore be designed to handle them explicitly and safely.

Nature of Retries and Duplicates

Retries and duplicate events can occur across multiple layers of the integration:

• Client-side retries
  → repeated API calls due to user actions (e.g., double submission) or UI timeouts
• Network or infrastructure retries
  → repeated requests caused by transient failures or communication issues
• Webhook delivery retries
  → repeated notifications sent by SPG when acknowledgment is not received or delivery fails
• Internal processing retries
  → reprocessing triggered by system errors or recovery mechanisms

See E.1 – Webhooks (Notifications) for detailed guidance regarding webhook acknowledgment behavior, notification delivery retries, and webhook processing strategies.

These scenarios may produce multiple occurrences of:

• the same API request
• the same transaction operation
• the same webhook notification

Omnichannel Retry Implications

In omnichannel scenarios, retries and duplicate events may originate from multiple independent channels interacting with the same transaction.

These channels may include:

• API-based integrations
• vTerminal operations
• Backoffice-triggered actions
• Other system-initiated processes

Because these channels operate independently, the same logical transaction may be:

• retried from different systems
• re-triggered through alternative operational flows
• processed concurrently across channels

This introduces additional duplication risks beyond single-channel integrations.

Incorrect handling patterns include:

• Treating operations from different channels as independent transactions
• Failing to correlate operations using shared identifiers (e.g. transactionID and merchant.merchantTransactionId)
• Executing duplicate operations due to lack of cross-channel coordination

A correct implementation must:

• Correlate all operations across channels using transaction identifiers
• Ensure that retries or actions initiated from any channel do not result in duplicate financial effects
• Treat omnichannel inputs as part of a single logical transaction lifecycle

Failure to handle omnichannel retry behavior correctly may result in duplicated operations across systems and inconsistent transaction state.

All operations originating from different channels must be treated as part of the same logical transaction when they refer to the same underlying payment. Failure to enforce this principle leads to duplicate processing across channels.

The Core Pitfall

The core issue arises when integrations assume that:

“Each request or event will be delivered and processed exactly once.”

This assumption is invalid in SPG integrations.

In reality, systems must operate under an at-least-once delivery model, where:

• the same operation may be executed multiple times
• the same event may be delivered more than once

Incorrect Implementation Patterns

Improper handling of retries and duplicates typically manifests as:

• Processing repeated API requests as independent transactions
• Not detecting or preventing duplicate transaction creation
• Executing the same operation multiple times (e.g., multiple CAPTURE attempts)
• Processing the same webhook notification more than once
• Not using notificationID to detect duplicate webhook deliveries
• Treating retries as new events rather than replays of the same event

These patterns result from assuming a single-execution model instead of a retry-tolerant model.

Expanded Idempotency Edge Cases

Beyond basic duplicate request handling, several advanced edge cases may lead to unintended duplicate processing if not explicitly addressed.

These include:

• Retrying a request with a new merchant.merchantTransactionId, resulting in a new transaction instead of replaying the original
• Reprocessing webhook notifications without validating notificationID, leading to repeated business actions
• Executing repeated CAPTURE or REFUND operations due to unclear transaction state
• Triggering retries after a transaction has already reached a final state
• Concurrent processing of the same transaction across multiple threads or services
• Misinterpreting transient failures and retrying operations that have already been successfully processed

Transaction-state confirmation and reconciliation should be performed using E.2 – Status Inquiry / Get Status when required.

When additional operational diagnostics are required, extended transaction visibility may additionally be obtained through Inquiry Details, as described in E.2.10 – Inquiry Details API.

These edge cases arise from incorrect assumptions about execution guarantees and system state visibility.

A robust implementation must:

• Enforce strict idempotency using stable identifiers
• Validate the current transaction state before executing any retry or additional operation
• Ensure that all operations are safe under repeated execution
• Prevent concurrent or conflicting updates to the same transaction

Failure to address these scenarios may lead to subtle duplication issues that are difficult to detect and resolve in production environments.

Status validation should be performed using E.2 – Status Inquiry / Get Status before retrying operations or applying additional transaction actions.

Correct Handling Model

A correct implementation must be idempotent and retry-safe, ensuring that repeated inputs do not produce repeated side effects.

This requires:

• Recognizing that identical requests may be replayed
• Ensuring that repeated operations do not create duplicate outcomes
• Treating webhook notifications as potentially duplicated signals
• Using identifiers (e.g., merchant.merchantTransactionId, transactionID, notificationID) to detect and control repeated processing

Each operation must be designed such that:

• processing it once or multiple times produces the same business and financial outcome without duplicate side effects
• no unintended duplication occurs at business or financial level

As defined in F.6.2 – Idempotency and Duplicate Protection, idempotency is a fundamental requirement for production-grade integrations.

Retries must only be applied to temporary error conditions (statusCode = Txxxx), using a controlled retry with exponential backoff strategy as defined in C.6 – Error Payloads and Handling Guidelines.

Retries must not be applied to validation or business error conditions (statusCode = Exxxx), which require correction of the request or user-driven resolution rather than automatic retry.

Relationship with Asynchronous Processing

Retries and duplicates are closely tied to asynchronous behavior.

Because:

• events may be delayed
• acknowledgments may fail
• systems may retry operations

duplicate delivery becomes unavoidable.

A correct implementation must:

• accept that duplicate events are normal
• distinguish between new events and replayed events
• ensure consistent state regardless of processing order or repetition

Failure to handle this relationship correctly leads to inconsistent outcomes under real-world conditions.

Consequences of Improper Handling

Failure to correctly manage retries and duplicates leads to severe operational issues:

• Duplicate charges or financial operations
• Multiple CAPTURE or REFUND executions for the same transaction
• Inconsistent transaction states across systems
• Duplicate order processing or fulfillment
• Increased reconciliation complexity
• Loss of trust due to incorrect user-facing outcomes

These issues are particularly critical in payment systems, where duplication directly impacts financial integrity.

Key Principle

Retries and duplicate events must be treated as normal and expected conditions.

Correct integration behavior requires:

• designing all operations to be idempotent
• detecting and controlling repeated processing
• ensuring that duplicate inputs do not produce duplicate effects

Any integration that assumes single execution of requests or events will produce incorrect, inconsistent, and potentially harmful outcomes in production environments.