Generate a stable idempotency key at the start of each agent checkout task; the key must be derived from the task intent and its input parameters (e.g., a hash of agent session ID + cart contents + timestamp bucket), not from a random UUID that a re-invoked agent will not regenerate identically
Pass the idempotency key in every mutating API call — Stripe (Idempotency-Key header), PayPal (PayPal-Request-Id header), and other PSPs each have their own header name — consult each PSP's current documentation for the exact header and behavior guarantee
Store the idempotency key and its outcome (success, pending, or failure with error code) in a persistent key-value store that the agent runtime can read on retry; if the stored outcome is success, return the cached result immediately without re-executing the API call
Set an expiry on idempotency keys consistent with your task retry window (e.g., 24 hours for a same-day purchase task); PSPs impose their own server-side idempotency key TTLs — check current PSP documentation and ensure your client-side retention period is shorter to avoid serving a cached success after the PSP has expired its record
For ACP checkout sessions, use the checkout_session_id returned by the /checkout_sessions endpoint as a natural idempotency anchor for all subsequent session update and complete calls; do not create a new session on retry if the original session ID is still valid
Test with simulated network partitions: verify that a retry after a timeout-but-success scenario returns the cached successful outcome rather than creating a second order, and that a retry after a genuine failure correctly re-executes
Known gotchas
LLM agents can be re-invoked by their orchestrator without any memory of prior tool calls — if the idempotency key is generated inside the LLM tool call rather than passed in from the orchestrator, a fresh invocation will generate a different key and produce a duplicate charge
PSP idempotency guarantees apply to identical request bodies; if the agent retries with even a minor payload difference (e.g., a floating-point price rounding difference), the PSP treats it as a new request and processes it independently — normalize all numeric fields before hashing the key
Idempotency key collisions across different customers or agents sharing a key namespace can cause one buyer's cached outcome to be returned for another buyer's request; namespace keys with a user or session-specific prefix
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp