Why idempotency keys in payments APIs need a full contract, not just a lookup

A payments API idempotency key is often implemented as a simple database lookup to prevent duplicate requests, but engineers argue this approach is incomplete and leaves double charges possible. A true idempotency contract must guarantee two things: the underlying work executes at most once, and every retry receives the original response with the same status and body. Without returning the original response, clients that retried due to network failures never recover the charge ID they need, making the retry safe for the server but useless for the caller. Implementations must also store a fingerprint of the request body alongside the key, rejecting any retry that sends the same key with different parameters rather than silently picking one. Common pitfalls like inconsistent JSON key ordering and timestamp fields in request bodies can cause false fingerprint mismatches, so canonical serialization is essential for reliable behavior.