Idempotency Key

An idempotency key is a unique identifier that a client includes in an API (Application Programming Interface) request to ensure that the operation is only performed once, even if the request is sent multiple times. In the context of payment APIs, idempotency keys prevent duplicate transactions caused by network timeouts, connectivity issues, or application retries.

The problem idempotency keys solve is straightforward but consequential. When a client sends a payment API request and the network fails before a response is received, the client does not know whether the request was processed. If it retries the request without an idempotency key, the payment provider may process it as a new, separate transaction, resulting in a duplicate charge on the customer's card. With an idempotency key, the provider recognizes the retry as a duplicate of the original request and returns the original response rather than processing a new transaction.

Idempotency keys are typically generated client-side as universally unique identifiers (UUIDs) and included in the API request as an HTTP header or request parameter. The payment provider stores each key with its associated result for a defined period (typically 24 hours to several days). Any subsequent request with the same key within that window returns the cached result without triggering a new operation.

Implementing idempotency key handling correctly is a mark of a well-engineered payment integration. It is particularly critical in high-availability systems, mobile applications (where network connectivity can be unreliable), and retry-heavy workflows like subscription billing where automated retries are a core feature.