Payment Idempotency

Overview

Payment Idempotency is a distributed-system reliability property that ensures repeated submission of the same logical payment intent does not create additional charges, invoices, payouts, or financial effects. Correct use of Payment Idempotency lets a client repeat an ambiguous request without creating another unintended effect, while preserving the original status, identifiers, response, and business outcome. Payment Idempotency must define the protected operation, client-supplied or derived key, uniqueness scope, request-equivalence rule, retention window, stored result, retry behavior, and conflict response.

A client assigns a stable identity to one payment intent, commonly through an idempotency key or unique order reference. Providers should define key scope, lifetime, parameter consistency, response replay, and partial-failure behavior. Payment Idempotency applies idempotent operation rules specifically to payment creation or mutation so retries do not create duplicate financial actions.

Retention also matters because a forgotten key can allow a delayed retry to become a new operation. Clients must reuse one key only for the same intent and reconcile after ambiguous timeouts before changing it. The server atomically associates that identity with the first accepted request and returns the existing result for legitimate repeats. Comparing payloads after execution is insufficient because concurrent duplicates may both create effects. Metrics for Payment Idempotency should separate first-attempt success, recovered operations, exhausted attempts, duplicate prevention, and added latency. The Payment Idempotency policy should define which failures are retryable, how long the decision remains valid, and how duplicate effects are prevented. Configuration changes to Payment Idempotency should be versioned and tested under burst, timeout, dependency failure, and restart conditions.