← Library

— notes

Why UUIDs Matter for Idempotency

2 min read#payments#go#distributed-systems
On this page
  1. The Problem
  2. UUIDs as Idempotency Keys
  3. Why UUID v7
  4. Key Takeaways

In payment processing, processing the same authorization twice is worse than rejecting it. A customer charged twice loses trust immediately. Idempotency keys prevent this.

The Problem

A client sends an authorization request. The network drops the response. The client retries. Without idempotency, the server processes the authorization again, resulting in a double charge.

UUIDs as Idempotency Keys

The client generates a UUID before the first attempt and includes it in every retry. The server checks: have I seen this UUID before? If yes, return the original response. If no, process the request and store the UUID with its response.

Why UUID v7

UUID v7 embeds a Unix timestamp in the first 48 bits, followed by random bits. This gives you:

  • Chronological ordering: UUIDs sort by creation time, which makes database indexes efficient
  • Uniqueness: the random component prevents collisions even at high throughput
  • Expiry: you can garbage-collect old idempotency records by inspecting the embedded timestamp

Key Takeaways

  • Idempotency keys prevent duplicate processing in distributed systems
  • UUID v7 provides time-ordered uniqueness without coordination
  • The embedded timestamp enables efficient cleanup of expired records
  • Always generate the idempotency key client-side, never server-side