An idempotency key lets you send the same request again without doing the work again. If your first attempt timed out, you cannot know whether Payve received it. Retry with the same key and Payve returns the first result instead of creating a second payout.
One key per operation. Same key on every retry. Never the same key for a different operation. These three rules are what stop a double payment. A new key on a retry tells Payve it is a new payout.

Where the header is required

GET requests ignore the header. A required key that is missing returns 400 validation_idempotency_key_required. A key longer than 255 characters returns 400 validation_idempotency_key_invalid.

How a key behaves

Keys are scoped to your account. Two businesses can use the same key value without touching each other.
1

First request

Payve runs the request and remembers the response for 24 hours.
2

Same key, same request, after it finished

Payve returns the stored response with the original status code, and adds the header Idempotent-Replayed: true. Nothing runs again.
3

Same key, while the first is still running

Payve returns 409 idempotency_conflict. Wait a moment and send the same request with the same key.
4

Same key, different endpoint or different body

Payve returns 422 idempotency_key_reused. The first request stands. This one is refused.

409: a request with this key is in flight

Retry with the same key after a short wait. Do not switch to a new key: the first request may still complete.

422: the key was used for something else

details.differs is body or route. The body comparison ignores the order of JSON keys, so reordering fields is not a different request. Changing any value is.
A 422 idempotency_key_reused is a bug in your code, not a transient failure. The first request under that key may already have moved money. Find out what it did before you send anything new.

What is and is not remembered

  • Successful responses are remembered for 24 hours.
  • Failed requests are not. If a request ends in an error, the key is released and you can retry with the same key.
  • Payouts, pay-ins and conversions are also de-duplicated permanently on your account and key. Sending a key you used for a payout last month returns that payout, not a new one.
The 24-hour window is how long a replay returns the stored response and how long a changed body is detected. It is not how long a key stays unique for a payout. Never recycle keys.

Choose a good key

Use a random UUID, or derive the key from your own record, such as payout-<your order id>.

When to retry

Cautions

A key created on each attempt is a different key each time. Create it once, outside the loop, and store it.
A changed body under an old key is refused with 422. A new payout needs a new key.
Two attempts made at different times produce two keys, and two payouts.
Replaying a bulk request with the same key returns the first response and creates nothing new. See Bulk payouts.
Payve delivers webhooks at least once. Record each event id so your own handler does its work once. See Handle events safely.