Payment State & Idempotency
Rule: a payment is a state machine with an idempotency key, never a boolean. paid = true
Payment Providers & Webhooks
Rule: a provider response and a webhook are external signals, not truth. The only source of
Order & Payment Consistency
Rule: money moved and the order updated are two facts in two places, and no transaction spans
Payment Ledger
Rule: payment status says whether a transaction succeeded; only a ledger says where the money
Refunds
Rule: a refund is a new transaction, not an undo. It has its own state machine, its own
Reconciliation
Rule: reconciliation is a legitimate source of change, not a silent patch. Every repair it
Fraud Detection
Rule: technically valid is not the same as trustworthy, and blocking too much costs more than
Settlement
Rule: "payment succeeded" is an intention; settlement is when the money actually arrives.