Design a payment system and ledger

01Separate purchase workflow from accounting

Design merchant checkout through one external processor, with authorization, one full capture, status and full or partial refunds. A payment intent tracks the purchase workflow. A ledger records financial movements in immutable journals. Exclude foreign-exchange conversion, lending, disputes and unrestricted transfers between merchants; those change the account and coordination model.

Use payment P81 for USD 25.00, represented as 2500 minor units. Amount and currency come from a validated order, not an editable browser total. Use integer minor units and currency metadata; not every currency has two decimal places. Store a provider-issued token rather than raw card details.

Authorization reserves spending capacity under the processor contract. Capture requests the financial movement. Settlement later transfers funds according to the processor arrangement, and paying the merchant is another movement. These are distinct events, not interchangeable success labels.

The customer may see pending while an external result is unknown. Retrying one operation must not create another logical charge, and posted journals must balance within each currency. For this design, acknowledged operations and postings must survive one zone failure under synchronous regional replication and safe failover. Regional disaster recovery is a separate promise.

Clarify whether the prompt means merchant card payments or transfers of existing wallet balances, which operations the processor supports, and what “success” means to the caller. The main design covers authorization, capture and refunds with durable pending states; the separate wallet variant changes the account transaction.

02Functional requirements

1. Create and authorize a payment. Validate merchant, order, amount and currency, create a recoverable payment intent and initiate authorization through the processor.

2. Capture and report status. Request one full capture for an eligible payment and expose authoritative local state, including pending or unknown external outcomes.

3. Refund safely. Support full or partial refunds against remaining captured capacity, with recoverable operation identities and visible progress.

4. Record and reconcile money movements. Post immutable balanced journals, compare processor and settlement evidence with local records and repair missing postings through the same validated routine.

03Non-functional requirements

These are illustrative interview assumptions, not product facts or measured benchmarks. Confirm them before choosing components, then validate the completed design under the stated workload. Here p95 means the 95th-percentile latency: 95% of measured requests take no longer than that value. Report errors and rejected work alongside latency; a fast failure is not a successful outcome.

1. Workload. Plan for ten million intents/day, about 2,315 new intents/s at the assumed peak and 9,260 status reads/s. Size authorization, capture, callbacks and refunds as separate local transaction work.

2. Local response and evidence freshness. Target 300 ms p95 for durable local command acceptance and authoritative status reads under admitted load. After verified processor evidence is durably received, target its local application within five seconds for 99% of outcomes. Neither target promises processor authorization, capture or settlement completion within that time.

3. Financial consistency. Permit one full capture claim per payment, keep each currency’s journal balanced and never promise refunds beyond captured amount minus successful refunds and unresolved reservations. Timeout does not release uncertain financial capacity.

4. Durability and safe availability. Require acknowledged operations and postings to survive one zone failure under synchronous regional replication and safe failover. When posting authority is unavailable, keep outcomes pending and refuse financial decisions from stale replicas; regional loss is a separate recovery contract.

5. Security and external retry limits. Authenticate merchant ownership and refund/correction authority, verify processor evidence and keep raw card data with the provider. Preserve operation identity; after the provider’s deduplication window expires, reconcile instead of blindly resubmitting.

04Trace the full payment with one database and adapter

Begin with a payment API, one transactional database and a bounded worker using one processor adapter. The API authenticates merchant M7, validates the order and stores P81 with a stable authorization operation and outgoing-work record. It returns accepted only after that state is durable. The worker can find the operation after a process restart.

After verified authorization and any required customer action, a capture command locks P81, checks amount, currency and capture eligibility, and claims its single capture slot. It stores operation C81 and its immutable provider key before the network call. The call runs outside database locks.

When verified processor evidence establishes the capture, one local posting transaction records that fact, creates its journal, updates payment status and saves a merchant notification event. Only then does the service report captured locally. A provider success followed by a failed local transaction requires replaying the evidence, not capturing again.

The worker can initially poll indexed durable work; a broker is optional. Webhooks and a reconciliation worker offer additional ways to recover the same outcome. They all call the same posting routine. Separate paths must not create independent journals for the same financial operation.

05Estimate transaction phases and long-lived records

Assume ten million new payment intents/day: about 116/s on average. A twentyfold peak is approximately 2,315 new intents/s. If clients make four status reads per intent, corresponding peak reads are about 9,260/s; aggressive polling can easily invalidate that estimate, so use bounded polling or notifications followed by status reads.

Separate authorization and capture can require four local transaction phases: initial authorization command, authorization outcome, capture claim and capture posting. At the assumed peak, that is about 9,260 transactions/s before refunds, callbacks and recovery. Benchmark this actual workload before deciding whether a single database needs sharding.

Ten retained records of 1 KB per intent produce 100 GB/day, or 36.5 TB/year. Seven years is about 255.5 TB logically before replicas and indexes. Historical records may move to a verified archive, but the request IDs, saved outcomes and recovery records needed by current operations must remain available.

At 2,000 unresolved operations/s, a five-minute processor incident adds 600,000 operations. If recovery completes 3,000/s while 2,000/s new work continues, net drain is 1,000/s and takes another ten minutes. This requires actual processor headroom; more worker threads cannot manufacture a higher downstream quota.

06Give each financial operation its own stable identity

Interfaces

Request a partial refund

POST /payments/P81/refunds

Send the refund with the merchant- and operation-scoped key described below.

Refund amount in integer minor units

{
  "amountMinor": 500
}

Stored records

Keys are scoped to the authenticated merchant and operation type. Reusing a key with a different amount conflicts. This deduplicates the same command; a separate per-payment capture claim prevents two different keys from creating two full captures.

An inbox durably receives verified provider events; an outbox records work and notifications with local state changes. Index unresolved operations by next-attempt time and merchant history by creation time plus payment ID. Status immediately after a write uses the authority or a proven caught-up replica; a reporting view cannot approve refunds.

07Explain the balanced journal before the posting algorithm

In double-entry accounting, each journal has debit and credit lines whose totals are equal within one currency. For this simplified platform model, processor receivable represents money the processor owes the platform; merchant payable represents money the platform owes the merchant. For the USD 25 capture, the journal uses integer minor units:

This records the claim and obligation, not settlement into a bank account.

The posting routine uses one transaction:

1. Lock operation C81 and validate the evidence's merchant, provider reference, kind, currency and amount.

2. Check whether the unique journal for that operation and posting kind already exists. If so, return its result.

3. Otherwise validate all account lines and totals, then commit the journal, entries, payment state, balance projection and outgoing event together.

No observer should see half a journal.

Restrict direct entry writes so every writer uses the posting transaction. A row-level check on individual entries cannot by itself prove that an arbitrary multi-row journal balances. A balance projection is a convenient total derived from the journal; it can be checked or rebuilt and is not an independent source allowed to override history.

Correct errors by adding an authorized reversing or correcting journal with an audit link, not by erasing the original. Internal balance alone is insufficient: a perfectly balanced journal for the wrong merchant or amount is still wrong.

08Make timeout recovery part of the capture flow

The processor may complete C81 and lose its reply. Keep C81 unknown and use its original provider identity for supported idempotent recovery or lookup. A new operation C82 could charge again. Local uniqueness does not force an external processor to remember a key beyond its documented retention window; after that window, reconcile rather than retry blindly.

Verified webhooks are evidence, not commands to post without checks. Authenticate the provider payload, persist the incoming event, and match it to the stored operation. Distinct provider events can describe the same capture, so webhook event deduplication and journal-operation uniqueness solve different problems. Out-of-order facts must not turn a captured payment back into pending or declined.

Claim capture and authorization cancellation through the same payment row. Require a known eligible authorization, matching full amount and currency, a valid capture deadline and no incompatible cancellation. Read the authoritative database clock after acquiring locks. A local eligibility check does not prevent the authorization expiring during the remote call; the resulting rejection or uncertainty still follows the recovery path.

Once capture may be in flight, cancellation cannot simply declare a successful void. Resolve the capture, then cancel an unused authorization or refund a confirmed charge according to the observed outcome. Never treat a browser redirect as processor evidence.

09Reserve refundable capacity before calling the processor

Suppose the captured amount is 2500 and no refund has completed. Two agents each request a refund of 2000 using different valid keys. Deduplicating keys does not help because the requests really are different. Both agents must lock the same capture-balance record before deciding how much to refund.

Agent A locks that record and computes available capacity as captured minus successful refunds minus unresolved reservations. Initially it is 2500, so A reserves 2000 and stores its refund operation plus outgoing work in one transaction. Agent B then sees only 500 available and is rejected before making any provider call. The external calls occur after those short transactions release their locks.

Releasing it merely because a timeout occurred would let B promise the same funds again.

Partial refunds repeat this capacity decision against the remaining amount. Refund journals are new entries linked to the original capture, never edits to its history. A screen may display available balance, but the command must recheck it atomically because another refund can win after the screen was loaded.

10Scale merchant-local decisions and isolate processor work

Add a queue when pending-work scans or provider scheduling need independent scaling. Publish operation IDs from the outbox, then let workers load current state and invoke the stored provider operation. Queue delivery can repeat; it is a wake-up mechanism, not permission to invent a fresh capture.

Bound concurrency by processor and merchant. Reserve recovery capacity for old unknown operations so a stream of new payments does not leave them unresolved forever. Limit new acceptance when the wait for pending work would become unacceptable, while preserving already accepted operations and current status reads.

When measured posting capacity is insufficient, partition independent merchants. Keep a merchant’s payment, journal, refund balance and local inbox/outbox where they can commit in one transaction. Hashing journal lines across unrelated shards would prevent one local transaction from committing the balanced journal. A very large merchant may need a carefully designed subledger later rather than arbitrary extra hash buckets.

Move stale-tolerant reporting and history to replicas or derived views, with an explicit freshness contract. Immediate payment status and every financial capacity decision remain authoritative. Static payment-method metadata is a safer cache target than mutable refund capacity. Cross-merchant transfers and multi-region concurrent posting remain separate extensions that require new coordination rules.

11Compare internal history with independent processor facts

Reconciliation compares provider operations and settlement records with local payments and journals. Match by provider account, operation reference, merchant, currency and amount. A missing local capture should go through the same outcome applier as a webhook; it should not trigger another capture call. An unmatched or conflicting fact becomes a durable review case with evidence.

Settlement is distinct from capture. Processor transfers, fees and merchant payouts require their own appropriate journals in the account model. The capture journal must balance, but recording it does not complete those later financial movements.

If the posting database is unavailable after the processor succeeds, retain pending local status and recover evidence when authority returns. Do not approve refunds from a stale replica to improve apparent availability. Synchronous replica placement and safe failover must actually meet the stated one-zone durability promise.

For regional recovery, state whether acknowledgments included a durable copy outside the region. If not, a regional loss may require restoring history and reconciling processor effects before replaying old commands. A backup that restores balances but loses operation identities can reopen duplicate-charge risk. Test restored uniqueness, evidence matching and unresolved operations as well as accounting totals.

12Observe money and unresolved age, not only HTTP success

Monitor unknown-operation age, unmatched amounts by currency, duplicate journal suppression, refund-capacity rejections, provider throttling and reconciliation backlog. Request latency matters, but ten healthy API instances do not make an unresolved capture financially complete. Measure local durable acceptance and authoritative reads against 300 ms p95, and verified-evidence receipt to local application against the five-second objective. Track external pending age separately: these targets do not bound processor completion.

Use separate, audited permissions for refunds and operational corrections. Enforce merchant isolation in queries, export paths, cache keys and reconciliation tools. Restrict provider credentials to adapters, verify callbacks and avoid logging card tokens, secrets or sensitive payloads. Immutable journals still need access controls and a deliberate retention policy.

Test crashes after processor success, after local posting and before queue acknowledgment. Race two refunds, submit two capture keys, replay different callbacks for the same capture, and restore a backup before applying old events. These tests cover separate guarantees; a balanced-total assertion alone does not prove that every external operation was recorded once.

Roll out posting changes with compatible readers and writers, a small merchant cohort and comparison against independent reconciliation. Stop unsafe posting when an invariant fails. The design deliberately accepts visible pending states and occasional unavailable decisions to preserve financial integrity and recover uncertain effects.

13Check the design against its requirements

Use the numbered requirements to check the final design. FR refers to the functional list; NFR refers to the non-functional list. Performance rows specify tests still required, not achieved benchmark results.

14Rapid revision

Remember: A timeout does not prove that no money moved. Keep the original operation and unresolved refund reservation until evidence resolves them.

Close with C81's lost response and the two competing 2000 refunds. They show why idempotency, balanced accounting and capacity reservation are separate protections rather than one generic “exactly once” feature.

15Optional prompt variant: transfer an internal wallet balance

This is an alternative prompt: Alice transfers an existing wallet balance to Bob inside the same service. It is not a merchant card capture. Choose same-currency transfers with no fees or overdraft, and keep both accounts and their journal in one database transaction domain. External deposits, withdrawals and currency exchange introduce different settlement boundaries.

A posted balance is the wallet’s committed net balance. An outgoing hold reserves part of that balance for an unfinished operation. Therefore spendable = posted balance − pending outgoing holds; expected incoming money is not spendable until posted. Store amounts as integer minor units with an explicit currency, and make every operation that changes posted or held funds follow the same account-locking rule.

Alice has $100 posted and $20 reserved for a different payment. She asks to transfer $60 to Bob, who has $15. The table displays dollars for readability; storage uses cents.

The $20 hold remains, so Alice has $20 spendable afterward. If another concurrent request also tries to transfer $60, it must observe the first committed transfer and reject for insufficient funds. Reading $80 before locking the accounts and spending it twice would overdraw the wallet, even if each transfer’s journal balanced.

Authenticate the caller and authorize access to the source wallet and any saved transfer result. Use a stable transfer ID scoped to the sender plus a fingerprint of source, destination, amount and currency. In the transaction, claim or read that unique identity first. Return an authorized matching completed result even if Bob’s wallet was later frozen; changed parameters conflict.

For a new transfer, use the same transaction:

1. Require a positive amount. Lock both accounts in stable account-ID order, then validate current debit authority, destination eligibility and matching currency.

2. Read posted and held balances under those locks and require Alice’s spendable funds to cover $60.

3. Commit a balanced journal, both balance updates, the successful transfer result and notification outbox together.

For customer wallet liabilities, debit Alice’s account by $60 and credit Bob’s by $60: the service’s total liability is unchanged. The journal and materialized balances must not be separate asynchronous commits. Never hold these locks while sending notifications.

After a timeout, retry or look up T81; do not create a new transfer identity merely because the reply was lost. TigerBeetle’s submission guidance explains stable transfer identity across retries, while PostgreSQL’s transaction example illustrates atomic account updates. If the accounts move to independent shards, an ordinary local transaction no longer covers both. Use a supported distributed transaction, or explicitly design reserved funds and a durable pending-transfer workflow with recovery. The shared distributed-workflow lesson explains those coordination choices; this variant stops at the single-database transfer.

Recall the key ideas

Answer from memory before opening each card. Explain why the choice works and what it costs. Revisit missed cards tomorrow.