The single most important property of a money-moving API is that retrying a request never moves the money twice. Idempotency keys are how you get there.
Imagine your service asks a payments API to send a payout. The request goes out, the payout is created — and then the network drops the response before it reaches you. Your service has no idea whether the payout happened. If it retries blindly, it might send the money twice. If it gives up, it might send nothing. Idempotency is how you escape that dilemma.
What an idempotency key does
You attach a unique key to a request that creates or moves money. The first time the platform sees that key, it performs the operation and stores the result against the key. If the same key arrives again, the platform returns the stored result instead of repeating the work. The retry is now safe: at most one payout is created, no matter how many times the request is sent.
Getting the details right
- Generate one key per logical operation, and reuse that exact key on every retry of it.
- Derive the key from something stable in your own system, so a retry after a crash still produces the same key.
- Send the key on any request that debits, credits, or transfers — not just the ones you expect to fail.
- Treat a returned "already processed" result as success, not as a duplicate to clean up.
Why we treat this as non-negotiable
On a payments platform, "it usually works" is not good enough — the failure mode is double-charging a real business. That is why every operation that moves money at Payve is designed to be safe to retry, and why we encourage every integration to send an idempotency key from day one.