Why this matters
- StreamHub processes creator payouts, subscription billing, and tip transactions — payment bugs mean lost revenue, double charges, or regulatory fines.
- Idempotency is non-negotiable: network retries must never create duplicate charges.
- The ledger is append-only; balances are computed, never directly mutated.
Payment system components
- Payment gateway — Stripe, Adyen, or Razorpay handles card tokenisation and PCI compliance.
- Ledger service — double-entry accounting; every debit has a matching credit.
- Idempotency store — Redis or DB keyed by idempotency key; returns cached response on retry.
- Webhook processor — async confirmation from payment gateway (charge succeeded, payout completed).
- Reconciliation engine — daily batch compares internal ledger with gateway settlement reports.
- Payout service — batch creator earnings to bank accounts on a schedule.
Double-entry ledger
Payment platform architecture
Every transaction creates balanced journal entries — total debits equal total credits.
CREATE TABLE ledger_entries (
id UUID PRIMARY KEY,
journal_id UUID NOT NULL,
account_id UUID NOT NULL,
amount_cents BIGINT NOT NULL, -- positive = credit, negative = debit
currency CHAR(3) DEFAULT 'USD',
description TEXT,
created_at TIMESTAMPTZ DEFAULT now()
);
CREATE TABLE accounts (
id UUID PRIMARY KEY,
owner_id UUID,
account_type VARCHAR(32), -- 'user_wallet', 'platform_revenue', 'escrow'
currency CHAR(3) DEFAULT 'USD'
);
def process_tip(from_user: str, to_creator: str, amount_cents: int, idempotency_key: str):
journal_id = uuid4()
entries = [
{"account_id": user_wallet(from_user), "amount_cents": -amount_cents},
{"account_id": creator_wallet(to_creator), "amount_cents": amount_cents - platform_fee(amount_cents)},
{"account_id": platform_revenue(), "amount_cents": platform_fee(amount_cents)},
]
assert sum(e["amount_cents"] for e in entries) == 0
ledger.append_journal(journal_id, entries)
The rest of this guide is part of Pro
Free covers every fresher guide in full. Pro unlocks Senior, Staff and Architect guides across every track.
Still to come · 5 sections
- Idempotent payment API
- PCI compliance boundary
- Webhook processing
- Reconciliation
- Scale estimates
Test yourself
Answer these before moving on — recall is what makes it stick.