Idempotency and retries

Why the key is mandatory

A connection can fail after LuxPay accepts a request but before your client receives the response. Repeating the request without a stable identity can create a second financial operation. An idempotency key identifies the same business intent across transport attempts.

Key location

The current wallet mutation contract carries idempotency_key in JSON for deposits, withdrawals, transfers, payouts, and settlements. Orchestrated payment endpoints use the Idempotency-Key header. Every endpoint page states the required location in its idempotency field.

Key generation

Use a UUID or another high-entropy identifier and persist it with your local request record before sending the network call. Do not use only a timestamp or user number. The same key must represent the same logical body. Changing the amount or wallet while reusing a key is a conflict and should be handled as HTTP 409.

Retry policy

Retry transport failures and selected 5xx responses with bounded exponential backoff and the same key. Do not automatically retry 401, 403, or 422. For 429, honor Retry-After when present. If LuxPay returns a successful duplicate result, treat it as the original operation result and persist its resource identifier.

Storage and reconciliation

Store the key, request-payload hash, LuxPay identifier, status, and attempt timestamps. This evidence lets you reconcile your system with the LuxPay ledger without depending only on mutable logs.