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
- Lock, idempotency, audit record, double-submit test. Pressing "pay" twice leaves balance +X, not +2X.
- 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.
- 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.
- Separate buckets. Trial, promo, purchase and subscription are distinct entities, not one
balance; the deduction order (free → bonus → paid) lives in one function. - Gate before expensive work. Check entitlement, limit and money before the external call (CPU, API, LLM); at zero balance it never happens.
- 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.
- 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.
- Read-modify-write under one lock or transaction; reading, computing and writing without it is a lost update.
- One source of truth. UI, cache and logs are derivatives; read incidents from the store.
Atomicity in the store
- Atomic check-and-increment:
UPDATE ... SET used = used + 1 WHERE used < max; rowcount 0 means exhausted — never SELECT → IF → UPDATE. - Compound primary key as idempotency:
PRIMARY KEY (code, user_id)blocks a repeat at the store, without a read first. - Counter upsert:
INSERT ... ON CONFLICT DO UPDATE SET value = value + excluded.value. - SQLite:
connect(timeout=30.0),PRAGMA busy_timeout=30000andjournal_mode=WALtogether; any one alone still surfaces "database is locked" under concurrent writers. - Non-relational store: conditional write with a version or compare-and-set, unique key on the idempotency pair, atomic counter increment. Where none exists, serialize mutations per subject through a single owner (a queue partitioned by subject id).
Promo codes and value operations
- Soft delete where history or foreign keys point at the row:
UPDATE status='finished', not DELETE; in an append-only store, write a compensating event. - Normalize once at the boundary (case, whitespace, charset); downstream trusts the canonical form.
- Structured failure:
(ok, reason_code, value)with codes such asnot_found,already_used,exhausted; the UI maps the code to a message. A bareFalseloses the reason. - Creator-scoped admin queries:
created_by = ?on every query, ownership checked on every mutation. - One constant drives every surface:
REFERRAL_BONUS = 30in store, UI text, share message and tests, so grep finds only the definition. - Pre-cap guard: check the cap before creating rows, so a refusal returns without side effects; state "unlimited" explicitly rather than cap 0.
Workflow
- Find the paths. Grep handlers for charge, debit, credit, grant, refund, invoice, balance, promo, referral, quota, limit, expire; mark every deduction and credit.
- Check each mutator against rules 2–8, and classify every provider call into the three outcomes; a missing unknown branch needs the pending record and reconciliation.
- Check refusals and promos: no rows on refusal, a reason code, "unlimited" stated explicitly; promos soft-deleted, keyed against repeats, no self-referral, bonus only for new accounts.
- Write the tests, names as the spec: double-submit; confirmed failure; timeout/unknown → pending, reconciled; refusal without side effects; cap edge; abuse case; warning at a limit.