Idempotency is the property that repeated submissions of the same logical operation produce the same effect. It is the load-bearing concept for any payment-mutating API: a network retry of a successfully-submitted pain.001 must not produce a second batch.
The standard mechanism is an *idempotency key* — a customer-supplied opaque string (typically a UUID) sent in a header (Idempotency-Key). The server caches the response keyed by (tenant, key, route, body-hash) for a defined replay window (24h is typical, 7d is conservative). A second request with the same key and the same body returns the cached response; a second request with the same key and a *different* body returns 409.
iso-compliant enforces Idempotency-Key as a mandatory header on every mutating route. The middleware is at apps/api/src/middleware/idempotency.ts and the responses carry an X-Iso-Compliant-Idempotent-Replay: true header on cache hits. The MsgId derivation at apps/api/src/lib/msgId.ts is keyed on the idempotency key so a replay always produces the same downstream bank-side MsgId.
A common buyer-side mistake: regenerating the idempotency key on retry (which defeats the whole mechanism). The correct pattern is to generate the key once at the start of the logical operation and pin it across all retries.