Idempotent Payment Requests

Idempotency in payment processing ensures that performing the same operation multiple times produces the same outcome as performing it once. This is critical because network failures, client timeouts, and server errors can leave the caller uncertain whether a request succeeded. Without idempotency, retrying a failed payment creation could result in the customer being charged twice. Stripe supports idempotency by accepting an Idempotency-Key header on all POST requests; if Stripe receives a request with a key it has seen before (within 24 hours), it returns the cached response from the original request.

The idempotency key should be generated deterministically based on the operation's intent, not randomly. For example, use a combination of user ID, order ID, and amount (e.g., `pay_user123_order456_2999`) so that the same logical payment always maps to the same key. Random UUIDs as idempotency keys protect against accidental double-clicks but not against application-level retry bugs where a new UUID is generated per attempt. Store the idempotency key alongside your order record before making the Stripe call, so you can always retry with the same key.

Beyond Stripe's built-in idempotency, your own system should enforce at-most-once semantics at the application layer. Use database constraints (unique indexes on order_id + payment_intent_id) and state machine patterns (order status must be 'pending' to initiate payment) to prevent duplicate payment attempts regardless of the payment provider's idempotency support. This defense-in-depth approach protects against double charges even in distributed systems with multiple server instances.