Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 38 ยท Projects and Practice

Project: A Marketplace Ledger

Build a double-entry style ledger for a marketplace in integer cents, covering sales, platform fees, seller balances, refunds, payout holds and a final reconciliation check.

A marketplace is, underneath, a ledger: a list of entries that explains where every cent is. If the entries always balance, you can trust your numbers, answer a seller's "where is my money?" and satisfy an accountant. In this project you build a small ledger in plain JavaScript that models what the Connect chapter described: sales with platform fees, refunds, payout holds and payouts. No network is needed, and the Stripe calls it mirrors are labelled in comments.

The idea: every movement has two sides

In double-entry bookkeeping, each transaction debits one account and credits another by the same amount, so the sum of all balances is always zero. Our accounts:

  • buyer_funds: money paid in by buyers (a stand-in for money received through Stripe).
  • seller:<id>: what we owe a seller.
  • platform_revenue: fees we keep.
  • paid_out: money that left to seller bank accounts.
flowchart LR
  B["buyer_funds"] -->|"sale 5000"| S["seller:alice 4500"]
  B -->|"fee 500"| R["platform_revenue"]
  S -->|"payout"| P["paid_out"]
  S -->|"refund"| B

Sales split into seller share and fee; payouts and refunds move money out again.

Step 1: the ledger class

Node.js A double-entry ledger

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Because every move subtracts from one account and adds to another, total() is always zero. If it ever is not, you have found a bug.

Step 2: refunds

A refund must decide who bears the fee. Here the policy is: the seller returns their share, the platform returns its fee proportionally. Compute the fee part by subtraction so the pieces add up.

Node.js Proportional refunds

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Extend the Marketplace class from step 1 with a refund(orderId, ...) method that moves fromPlatform from platform_revenue and fromSeller from the seller account back to buyer_funds. Keep a map of orders so you can look up the sale and fee. Reject refunds that would exceed the original amount.

Step 3: payout holds and reconciliation

Real marketplaces do not pay out immediately, they wait until the order is delivered and the dispute window has passed. Model that with an available balance computed from entries older than the hold.

Node.js Releasing funds after a hold

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

How this maps to Stripe

Ledger idea Stripe object
Sale and fee PaymentIntent with application_fee_amount
Seller balance Connected account balance
Payout Payout or a scheduled payout
Refund Refund with optional reverse_transfer and refund_application_fee
Reconciliation Balance transactions and reports

Your own ledger remains valuable even with Stripe: it records business meaning (orders, sellers, policies) that Stripe's objects do not know, and you reconcile it against Stripe's balance transactions regularly.

Make the ledger append-only. To correct a mistake, add a new reversing entry instead of editing history. That gives you an audit trail.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In double-entry bookkeeping, what is always true about all account balances?

    Each entry subtracts from one account and adds to another, so the total never changes from zero.
  2. 2. Why compute the seller share as sale minus fee?

    Rounding both parts separately can lose or gain a cent.
  3. 3. Why hold seller funds for several days?

    A hold protects the platform from paying out money it may have to return.
  4. 4. How should a mistake in the ledger be fixed?

    Append-only ledgers keep history intact and make audits possible.

Summary

  • A marketplace is a ledger: each movement has a source and a destination of equal amount.
  • Use integer cents and subtract to avoid rounding drift.
  • Decide refund policy for fees, and hold funds until the dispute window passes.
  • Reconcile your ledger against Stripe balance transactions.

Next: Payments Practice Exercises