Idempotency

Idempotency lets you safely retry requests without risk of performing the same operation twice. This is useful when a request is interrupted by a network error or a timeout: you can retry it with confidence, knowing that the operation runs at most once.

Every POST request must include an Idempotency-Key header. A POST without it is rejected with 400. GET requests are naturally idempotent and never require a key.

Sending an idempotency key

To make a request idempotent, provide a unique value in the Idempotency-Key header. The key may be any string up to 255 characters; we recommend a UUID.

Send a distinct key for each distinct operation. Reusing a single key across different operations on the same payment — for example, creating it and later refunding it — is not supported, because each operation carries a different request body.

The first request with a given key is executed and its response is stored. Any later request with the same key returns that stored response — including the same status code and body — instead of running the operation again.

How keys behave

Situation	Result
Same key, same request body	Returns the stored response of the original request.
Same key, different request body	Returns an error: the key has already been used with different parameters.
Same key while the first request is still in progress	Returns an error: a request with this key is already being processed.
Key reused after it has expired	Treated as a new request.

Idempotency keys are stored for 24 hours. After a key expires, it can be used again for a new request.

Keys are scoped to your account, so they never collide with keys used by other accounts.

Which requests to send a key with

The key is required on every POST: creating payments, payouts and appeals, confirming, canceling and refunding payments, and uploading files.

Sending an idempotency key#

How keys behave#

Which requests to send a key with#

Sending an idempotency key

How keys behave

Which requests to send a key with