A payment request hits a network snag. Did the charge go through, or did it disappear? Retrying without a safety plan could charge the customer twice. An idempotency key is a request identifier that lets the payment processor recognize repeated submissions as the same transaction. section 6.4.2 section 10.2.2
The safety plan is simple:
- Generate a unique key for the payment, typically a UUID, and send it with the request. section 6.4.2
- Reuse that exact key on every retry. A fresh key on each attempt would give each attempt a different identity. section 10.2.2
- Have the server check whether it has already processed a payment with that key. The payment processor can then recognize duplicates rather than treat them as new transactions. section 6.4.2 section 10.2.2
This matters for GraphQL mutations, which change data and are commonly sent over HTTP POST. Unlike REST methods such as PUT and DELETE, a mutation needs idempotency designed into its payload. A read-only GraphQL query does not change state just because it is repeated. section 6.4.2 section 6.12
Listing 6.3 GraphQL Mutation with Idempotency Key
# The Client sends the mutation with a unique key
mutation {
processPayment(
amount: 50.00,
idempotencyKey: "a1b2c3d4-e5f6-7890-1234-56789abcdef0"
) {
status
transactionId
}
}The payment mutation sends an idempotencyKey alongside the amount. A retry of this payment must keep the same key. section 6.4.2 section 10.2.2
A key is a safety measure, not a retry strategy by itself. A resilient payment service can also use timeouts, exponential backoff, and a fallback when retries run out. Those measures address different problems; the key helps keep the extra attempts from becoming extra charges. section 10.2.2 section 10.4.2



