Idempotency Key

Overview

Understand the idea

An idempotency key is a client-supplied identifier used so retries of one intended API command can return the same outcome instead of performing the command again. It is especially important for creating payment instructions, sending payouts and issuing refunds when a request times out after the server may already have processed it.

What actually happens

The client generates a sufficiently unique key for the logical operation and sends it as documented. The server stores the key with the request identity, relevant parameters and resulting operation. If the same key is retried, it returns or references the prior result under defined rules rather than creating another operation. Providers vary in key retention windows, scope and how they handle the same key with changed parameters. The merchant must persist the key across worker restarts and retries instead of generating a new one every time.

A crucial implementation detail is that the business intent must remain stable. The same key reused for a different amount or recipient should not quietly create a new payout under an ambiguous contract. Many providers reject mismatched parameters, cache a result for a limited period or scope keys to one account. Keep a durable mapping from internal payout ID to provider request key, amount and expected beneficiary. If the provider later loses the key record, reconcile the underlying transfer before deciding whether it is safe to submit a new request.

Decisions and failure cases

Idempotency is conditional on the provider's actual contract and retention period. It may not protect against manual transfers from a wallet or repeated requests after the key expires. Applications still need to reconcile on-chain outcomes and guard order state transitions against duplicate webhooks.

Related concepts

API Versioning, HMAC Signature, Webhook Replay.

Further reading

Stripe idempotent requests.