Course contentsShow
← System Design
Lesson 1033 of 1,91926. Idempotency and RetriesFree lesson

Idempotency Keys in Payment Systems

How payment processors use client-generated idempotency keys to prevent duplicate charges and ensure exactly-once semantics.

Idempotency Keys in Payment Systems

What You'll Learn

How payment processors like Stripe and PayPal use client-generated idempotency keys to prevent duplicate charges and guarantee exactly-once payment semantics.

The Critical Challenge

Imagine you're buying concert tickets for 500.Youclick"PayNow,"butthenetworkhiccups—younevergetaconfirmation.Didthepaymentgothrough?Ifyouretryanditactuallychargedtwice,you′vejustpaid500. You click "Pay Now," but the network hiccups—you never get a confirmation. Did the payment go through? If you retry and it actually charged twice, you've just paid 1,000.

Payment processors solve this with idempotency keys: unique identifiers the client generates and sends with each payment request.

How It Works

When your client initiates a payment, it generates a unique key (like a UUID) and includes it:

POST /v1/charges
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
  "amount": 50000,
  "currency": "usd",
  "source": "tok_visa"
}

The payment processor stores this key along with the request details. On subsequent requests with the same key, instead of processing a new charge:

  1. If the original is still processing → return "request in progress"
  2. If the original succeeded → return the cached successful response
  3. If the original failed → return the cached failure response

This means you can safely retry the exact same request multiple times, and you'll only be charged once.

Real-World Pattern

Payment systems typically keep idempotency keys valid for 24 hours. After expiration, the same key could theoretically be reused (though clients should generate fresh keys). The key is scoped to the specific account and operation type, preventing collisions across different merchants.

Key Takeaway: Idempotency keys in payment systems transform non-idempotent financial operations into safe, retryable requests by creating server-side deduplication based on client-generated unique identifiers—eliminating double charges even with network failures or client retries.