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

These scenarios may produce multiple occurrences of:

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

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.

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., merchantTransactionId, transactionID, notificationID) to detect and control repeated processing

Each operation must be designed such that:

• processing it once or multiple times yields the same final result
• 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.

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.