Idempotency là persisted protocol, không phải cache mẹo

Timeout khiến client không biết effect đã xảy ra; payment endpoint phải trả cùng semantic result cho cùng command identity.

Contract

Idempotency-Key scoped theo caller/operation; canonical request fingerprint. First request tạo processing/result record; duplicate cùng payload replay response, khác payload conflict.

Atomicity

Unique key + transaction/locking đảm bảo một owner thực thi effect. Record status PROCESSING/SUCCEEDED/FAILED_UNKNOWN; crash recovery có lease/timeout và provider reconciliation.

Money và provider

Minor units/decimal, currency explicit; không dùng binary float. Tách internal payment ID, client key và provider reference; redact provider payload/token.

Tests

Concurrent duplicates, timeout after commit, crash before/after provider effect, mismatched payload, key expiry và replay. Verify one effect và stable response/audit.