money-path-safety

Money path safety

Applies to any path that deducts, credits, grants, expires or limits value: payments, balances, quotas, promo codes, referrals, subscriptions. A bug here is silent, permanent and spends real money.

Rules

1. Lock, idempotency, audit record, double-submit test. Pressing "pay" twice leaves balance +X, not +2X.
2. Idempotency by default: operation key (invoice id, event id, request id) + recorded outcome + early return. Run the handler twice — the second run is a no-op.
3. Three outcomes, not two. For every payment or value-provider call, classify what came back:
   • confirmed success → debit exactly once;
   • confirmed failure → no debit, record the rejection;
   • unknown — timeout, reset connection, 5xx, process death between the call and your write → neither debit nor refund yet. An unknown outcome may exist on the provider side: write a pending record under the idempotency key, then reconcile with the provider (query by key, webhook, statement) before debiting or refunding. Never charge twice, never drop the case silently. A timeout is not a failure.
4. Separate buckets. Trial, promo, purchase and subscription are distinct entities, not one balance; the deduction order (free → bonus → paid) lives in one function.
5. Gate before expensive work. Check entitlement, limit and money before the external call (CPU, API, LLM); at zero balance it never happens.
6. Audit record per mutation — one per credit, debit, grant, refund or expiry, with subject (or pseudonymous) id, amount, currency or unit, operation, idempotency key, outcome. Grep by subject reconstructs the history. Identifiers only: no secrets, tokens, card numbers or free-form personal data; the trail is access-controlled, and application logs are not a substitute.
7. No silent except on side effects. Swallowing an exception is fine in cleanup, never on money, auth or data loss: log and fall back, or fail loudly.
8. Read-modify-write under one lock or transaction; reading, computing and writing without it is a lost update.
9. One source of truth. UI, cache and logs are derivatives; read incidents from the store.