Idempotency keys for transfer reversals

Scope the key to the intent, not the request

The intent is "recover finding X" — so the key derives from the finding id: clawback-{id}. Keys derived from request UUIDs, timestamps or random values are unique per attempt and therefore useless: every retry carries a new key and Stripe happily executes each one. Ask what would make two executions "the same operation" and encode exactly that in the key.

// Right: retries collapse onto one execution
const key = `clawback-${finding.id}`;

// Wrong: every retry is a brand-new operation
const key = crypto.randomUUID();

The 24-hour expiry nobody plans for

Stripe idempotency keys expire after 24 hours. A retry arriving later genuinely re-attempts the operation. The key therefore cannot be the whole defence — it handles the retry storm; the worker handles the long tail. Before acting, read the live transfer: if amount_reversed already reflects this finding, stop. One API call removes the entire class of late-retry duplicates.

The double-guard pattern

Check live state → derive key from intent → execute → persist Stripe’s response against the finding. Four steps, every money-moving job, no exceptions. Persisting the original response matters as much as the guard: when support asks "did this happen?", the answer is a stored receipt rather than a reconstruction.

What FeeGuard does about it

Every automated clawback derives its key from the discrepancy id, workers re-read live transfer state before acting regardless of queue age, and the append-only audit trail stores Stripe’s original response against the finding. The pattern is not clever — it is simply enforced everywhere, every time, which is the part teams find hard to sustain by hand.