Safe retries with Idempotency-Key

Retry mutating API calls without creating duplicate payments or payouts.

Send Idempotency-Key on POST

All tenant-authenticated POST routes under /v1/* accept an optional Idempotency-Key header (1–255 printable ASCII). Keys are scoped per tenant environment (live and test twins do not share keys). Requests without the header behave exactly as before.

Same key + same method/path/body within 24h → replay the stored response with Idempotent-Replayed: true.
Same key + different body → 409 idempotency_key_reused.
Same key while the first request is still in flight → 409 idempotency_request_in_progress (retry later).
5xx and interrupted requests are not stored — retry with the same key is safe.

Relationship to externalRef

On payments, externalRef remains correlation-only. On merchants and payouts, externalRef stays the resource-level idempotency key and works independently of Idempotency-Key.