> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cashweb.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Safe retry contract for partner write operations.

Use `Idempotency-Key` on write operations:

* `POST /transactions`
* `POST /transactions/{id}/cancel`

## Required Header

```http theme={null}
Idempotency-Key: <unique-key-per-business-action>
```

## Retention Window

Idempotency responses are retained for 24 hours. Keep keys in your logs/trace context to support replay diagnostics.

## Rules

1. New business action => new idempotency key.
2. Retry same business action => same idempotency key.
3. Reusing a key with a different payload returns `409 Conflict`.

## Conflict Matrix

* Same key + same payload + completed prior response: returns cached success.
* Same key + same payload + in-flight request: returns conflict/in-progress signal.
* Same key + different payload: returns `409`.

## Merchant Reference Interaction

`merchant_reference` is a separate canonical uniqueness key. If the same reference is reused with conflicting intent, transaction creation returns `409` even with a different idempotency key.