Generate a stable, unique idempotency key per payment attempt (e.g., a UUID tied to the order ID and attempt number) before making the API call
Include the idempotency key in the Idempotency-Key request header on every PaymentIntent creation or charge request
On receiving a network timeout or 5xx response, retry the request using the same idempotency key; Stripe will return the result of the original request if it succeeded
On receiving a 409 conflict response, inspect the body to determine if the idempotency key was used with different parameters; if so, generate a new key and a new attempt
Store the idempotency key and the resulting payment ID in your database atomically before returning success to your application layer
Expire or retire idempotency keys after the payment reaches a terminal state to prevent accidental reuse of keys across different orders
Known gotchas
Idempotency keys must be scoped to the exact same request parameters; reusing a key with different amount or currency values will return a 409 error, not create a new charge
Stripe idempotency keys expire after 24 hours; retrying a request with the same key after expiry creates a new request rather than returning the cached result
Idempotency does not protect against application-level bugs that call the payment API twice with different keys; also implement business-logic deduplication at the order level
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?