Transaction integrity controls ensure that payment operations are executed exactly as intended, without duplication, omission, or inconsistency.

These controls are essential in distributed and asynchronous environments, where multiple inputs, retries, and delayed events may affect the same transaction.

SPG integrations must assume that exactly-once delivery semantics are not guaranteed across distributed communication channels.

Idempotency and Duplicate Prevention

All transaction operations must be designed to be idempotent, ensuring that repeated execution of the same logical operation does not produce unintended side effects.

• The Merchant system must:
  • Assign unique identifiers to each transaction operation
  • Detect and safely handle duplicate requests
  • Ensure that retries do not result in multiple executions of the same action

Duplicate scenarios may occur due to:

• Network retries
• Client-side resubmissions
• Asynchronous notification re-delivery

Previously captured or replayed transaction events must also be safely detected and rejected.

The system must ensure that duplicate events or requests do not lead to multiple charges, captures, or state transitions, ensuring that all operations remain consistent with the expected transaction lifecycle (as defined in C.4 – Transaction State Transition Model).

For operational duplicate, retry, and asynchronous edge-case handling patterns, refer to F.3.5 – Edge Cases and Operational Pitfalls.

Safe Retry Mechanisms

Retries are a natural part of distributed systems but must be carefully controlled.

• The Merchant system must:
  • Retry only when the outcome of a previous operation is unknown and cannot be determined through available transaction-state evidence, including Status Inquiry / Get Status when required (see E.2 – Status Inquiry / Get Status).
  • Avoid retrying operations that have already been confirmed as successful or failed
  • Ensure that retries are performed with the same identifiers and context

Blind retries without state awareness may lead to duplicate operations or inconsistent transaction outcomes.

Ordering and Concurrency Control

Transaction updates may arrive out of order or be processed concurrently.

• The Merchant system must:
  • Ensure that operations are applied in a logically consistent order
  • Prevent conflicting updates from being applied concurrently
  • Handle delayed or out-of-order events without corrupting transaction state

This is particularly relevant when handling:

• Asynchronous notifications
• Parallel processing of transaction updates
• Multiple operations affecting the same transaction

Improper handling of ordering or concurrency may result in invalid state transitions or inconsistent transaction histories.

Consistency of Transaction State

All transaction updates must be consistent with the expected lifecycle of the transaction.

• The Merchant system must:
  • Validate that each operation is allowed in the current state
  • Prevent invalid or unexpected transitions
  • Ensure that the transaction state reflects the actual outcome of operations

Operations must not be executed based solely on external inputs without verifying their consistency with the current transaction context.

When multiple inputs are received (e.g., API responses and asynchronous notifications), the system must ensure that the resulting state is coherent and consistent.

Correlation and Traceability

All transaction-related events and operations must be traceable and correlated.

• The Merchant system must:
  • Maintain consistent identifiers across all operations
  • Correlate requests, responses, and notifications to the same transaction
  • Ensure that each operation can be consistently traced throughout its lifecycle

Proper correlation ensures that:

• Duplicate or conflicting events can be detected
• Transaction history can be reconstructed accurately
• Operational issues can be diagnosed effectively

For operational observability, monitoring, and diagnostic guidance, refer to F.5 – Logging and Monitoring Best Practices.

Security Enforcement

Transaction integrity controls must be enforced consistently across all flows.

The Merchant system must ensure that:

• Duplicate requests and events are safely handled
• Retries are controlled and state-aware
• Transaction updates are applied in a consistent and valid order
• No operation is executed without verifying its consistency with the current transaction state
• All transaction events are properly correlated and traceable

Failure to enforce transaction integrity controls may result in duplicate charges, inconsistent transaction states, or incorrect execution of payment operations.