Design a Payment System

1Requirements

2Back-of-envelope estimation

3API design

4High-level design

Checkout tokenizes card details directly against the PSP (Stripe Elements), so raw PANs never touch platform servers and PCI scope collapses to SAQ-A. The order service then calls the payment service with an idempotency key derived from the order attempt.

The payment service is the orchestrator and keeps a state machine per payment. On a new request it writes the payment row in 'created', then calls the PSP to create/confirm a PaymentIntent, passing the same idempotency key to Stripe so PSP-side retries are also safe. State transitions are recorded before and after each external call so a crash at any point leaves a resumable record rather than mystery money.

Confirmed outcomes are written to the ledger service: every transaction is a balanced set of double-entry postings (debit PSP receivable, credit merchant payable and platform fee revenue) inside one ACID transaction in Postgres. The ledger is append-only; corrections are new reversing entries, never updates, which is what makes it auditable.

Asynchrony rides on a transactional outbox: the ledger commit and an outbox event are one DB transaction, and a relay publishes to Kafka, so downstream consumers (order fulfillment, notifications, analytics, payout scheduling) see exactly the committed truth. PSP webhooks flow into the same event backbone after signature verification and dedup, advancing payment state machines for async outcomes like disputes.

A scheduled payout service aggregates each merchant's payable balance from the ledger, initiates transfers via the PSP's payout API (again idempotently), and records the corresponding ledger entries. Nightly reconciliation jobs pull PSP settlement files, match them against ledger transactions three ways (internal ledger vs. PSP records vs. bank statement), auto-classify known mismatch patterns (timing, fees, currency rounding), and open cases for humans on the rest.

5Data model

6Deep dives

7Rapid implementation: build the MVP

Theory is table stakes. Here is how you would stand up a working version fast, on a budget, with the core algorithm in real code.

1. 01Create Postgres tables payments, idempotency_keys, ledger_transactions, and ledger_entries; every amount is an integer in minor units (cents).
2. 02Write the idempotency middleware and mount it on POST /payments and POST /refunds; require the Idempotency-Key header.
3. 03Integrate Stripe test mode: create and confirm a PaymentIntent server-side, passing the same idempotency key through to Stripe.
4. 04On confirmed success, post the balanced double-entry ledger transaction (receivable debit, merchant payable and fee credits) in one DB transaction, then store the response against the idempotency key.
5. 05Add the webhook endpoint: verify the Stripe signature, insert the event with a unique event_id (duplicates no-op), and advance the payment state machine only along legal transitions.
6. 06Add a sweeper cron that finds payments stuck in pending for over 10 minutes, queries Stripe for the intent's real status, and resumes the state machine; never guess.
7. 07Write a nightly reconciliation script that pulls Stripe balance transactions and diffs them against the ledger, printing every mismatch.
8. 08Test with Stripe CLI webhook replays and duplicate POSTs to prove the same key never charges twice.

export function idempotency(pool: Pool) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const key = req.header("Idempotency-Key");
    if (!key) {
      return res.status(400).json({ error: "Idempotency-Key required" });
    }
    // atomic claim: unique constraint decides who runs the handler
    const claim = await pool.query(
      "INSERT INTO idempotency_keys (key, status) " +
      "VALUES ($1, 'in_progress') ON CONFLICT (key) DO NOTHING " +
      "RETURNING key",
      [key]
    );
    if (claim.rowCount === 1) {
      res.locals.idemKey = key; // handler stores its response under this
      return next();
    }
    const prior = await pool.query(
      "SELECT status, response FROM idempotency_keys WHERE key = $1",
      [key]
    );
    if (prior.rows[0].status === "in_progress") {
      // original attempt still running: report it, never re-execute
      return res.status(409).json({ error: "request already in progress" });
    }
    return res.status(200).json(prior.rows[0].response); // replay outcome
  };
}

-- A $50.00 capture: all rows commit together or not at all.
BEGIN;

INSERT INTO ledger_transactions (id, type, payment_id, external_ref)
VALUES (11, 'capture', 42, 'pi_3XyzStripeIntentId');

-- balanced postings in integer cents: debits equal credits
INSERT INTO ledger_entries
  (transaction_id, account_id, direction, amount_minor) VALUES
  (11, 1001, 'D', 5000),  -- psp_receivable
  (11, 2042, 'C', 4825),  -- merchant_payable (merchant 42)
  (11, 3001, 'C', 175);   -- platform_fee_revenue

-- invariant check: divide by zero aborts the whole transaction
-- if debits and credits do not net to zero
SELECT 1 / CASE WHEN COALESCE(SUM(
  CASE direction WHEN 'D' THEN amount_minor ELSE -amount_minor END
), -1) = 0 THEN 1 ELSE 0 END
FROM ledger_entries WHERE transaction_id = 11;

COMMIT;
-- corrections are new reversing entries; rows are never updated