Glossary
What is an idempotency key?
An idempotency key is a unique value sent with a request so that repeating it has the same effect as sending it once. Why agents need one.
An idempotency key is a unique value a client attaches to a request so that, if the same request is sent again with the same key, the server returns the original result instead of performing the action a second time.
How does it work?
Networks fail in the worst place: after the server acted but before the client heard back. Without a key, the client can't tell whether to retry, and retrying a payment might charge twice. With a key, the server remembers what it did for that key and replays the answer. Stripe's API supports idempotency keys on requests for exactly this reason, and documents that keys may be removed once they are at least 24 hours old.
In practice
The key must identify the intended action, not the attempt. Generate it once when you decide to pay, store it with the task, and reuse it on every retry. A fresh key on each try makes the protection useless. For agents, the tool description should say so explicitly, because models otherwise treat each call as new. A good key is random and long enough not to collide, such as a UUID, or derived from the task, such as an order ID plus the item being paid for. If two genuinely different payments could end up with the same derived key, add something that tells them apart.
What it does not mean
- An idempotency key is not a secret or an authentication token.
- It doesn't stop two genuinely different payments for the same amount; that's what it's supposed to allow.
- It isn't a timestamp or request ID generated per attempt.
Where does Veyra fit?
Veyra's create_payment requires idempotency_key. Its tool description tells agents to reuse the same key for a retry of the same payment, that a new key means a new payment that will spend again, and never to create a second payment because they're unsure the first worked.
Sources
Guides that use this term
- How to stop an AI agent making duplicate paymentsAgents retry when unsure, and retries can pay twice. Idempotency keys, status checks and tool wording that keep one intended payment to one payment.
- How to test AI agent payments without real moneyRun an agent's payment flow end to end on a simulated rail: what to test, how to tell simulated from real, and what a testnet does and doesn't prove.
This page explains how agent payments and the related technology work. It is not financial, investment, legal or tax advice. Protocols and provider features change; check the linked official sources before relying on a detail.