Idempotency

Retry safely after timeouts and network errors.

Send an Idempotency-Key header (1–255 characters) on every POST. Derive it from your own record — an order ID for a payment, a refund-request ID for a refund — so a retry after a crash or deploy reuses it.

POST /v1/payments/{id}/refunds requires an Idempotency-Key. Requests without one fail with 400 idempotency_key_required.

Behaviour

Same key + same request → the original result is returned with Idempotent-Replayed: true.
Same key + different body, method or path → 409 idempotency_key_reused.
Two concurrent requests with the same key → one runs; the other gets 409 idempotency_request_in_progress. Retry shortly with the same key.
After a 5xx or timeout, retry with the same key. For refunds the key is stored with the refund itself, so the retry always returns that same refund and can never refund twice — even if the first attempt reached the provider before failing.

Keys are scoped to your organization and environment. Stored responses are kept for at least 24 hours; the refund-level key never expires.