Joseph Leporati

Engineering notes

Writing: commissions

Notes on building and running production systems: payments and ledgers, multi-tenant architecture, reliability and performance, and applied AI. By Joseph Leporati, software engineer and technical program manager in Monroe, Louisiana.

· 7 min read · commissions

Designing a Commission Engine That Survives Refunds and Chargebacks

Commission balances drift because a single mutable number can't record why it changed. Build the engine as a double-entry ledger instead. Postings are insert-only, every entry sums to zero, and refunds or chargebacks are posted as exact reversals of the original entry, never as edits. Give each party and holdback its own account, derive balances from postings, and run trial-balance and clearing-account checks on every batch so drift shows up within a day.

Read the article

· 7 min read · payments

Why Did We Get Charged Twice? Designing Idempotency for Payments

Most double charges come from a timeout. The first request reaches the processor, the response gets lost, and the client retries, so the system charges again. The fix is a client-generated idempotency key, stored atomically with the first attempt and backed by a database uniqueness constraint. An optional distributed lock covers the check-then-create race. Before you trust it with real money, test deliberate replays, timeouts and concurrent duplicates.

Read the article