Pay Phone — Build Spec / Dev Handoff v1

Date: 07/17/2026 · Status: logic locked, ready to build · One-liner: People pay to call your phone.

A marketplace for scheduled, time-boxed 1:1 video calls between fans and verified talent ("celebs"). Fans pay per call; celebs set prices and hours; the platform is the switchboard and takes a cut. Web-first for every transaction, native app as the daily surface.

0. The locked stack

Layer	Choice	Why / notes
App (iOS + Android)	Expo / React Native	Same toolchain as TextingParents; one codebase both platforms. Role decided by signed-in number, not by which app.
Web (site + booking + call + my-bookings)	Static + a thin API	`~/personal-projects/pay-phone/site/` is the built reference. Book, pay, and take the call all work in-browser.
Payments	Stripe — Connect (Express) for talent payouts, PaymentIntents for booking	Apple Pay is a payment METHOD on Stripe web checkout. NO Apple IAP anywhere. Apple's cut = $0.
Live video	LiveKit	Same as TextingParents: rooms, egress→R2 recording, CallKit/PushKit for native call ring.
SMS	Twilio	Join links, T-15 reminders, drops. The SMS channel is the growth loop — not optional.
Recording storage	Cloudflare R2	LiveKit egress target; MP4/AAC (iOS can't play OGG).
Moderation	Hive AI (or Rekognition)	Server bot participant samples frames; audio→text classifier.
Identity	Phone number = account, OTP via Twilio	Both sides. See §5.
Transactional email	Resend	E1–E6. From hello@joinpayphone.com.

Domain: joinpayphone.com (⚠️ registration unconfirmed — verify before deploy). Entity/Apple/Stripe/LiveKit/Twilio accounts: founder, same enrollment path as TextingParents.

1. The money rules (single source of truth)

Split: 80% talent / 5% manager / 15% platform. Platform pays Stripe fees out of its 15%.
Capture at booking, SPLIT ONLY ON CALL COMPLETION. Funds held between. No celeb clawbacks, ever.
Talent payout: Stripe Connect instant payout (per-call, at completion) — reads "landed." Standard next-day is the free alternative.
New-payphone reserve (D9): hold 10% for the first 30 days OR first $2,000 earned (whichever clears first), then release to full instant. Established payphones: no reserve. The reserve funds every fan-side remedy (refunds, chargebacks, reports) so no clawback is ever needed.
Extension price (D8): (service price ÷ service minutes) × extension minutes. 10-min $100 → $10/min → +5 = $50. Splits 80/5/15, settles with the base call.
All-in pricing: the price on the page is the total. No service fees added at checkout.
Manager 5 pts applies to hours, drops, and extensions equally. On a conduct-forfeit (no talent payout), the manager earns nothing.

2. Booking lifecycle state machine

                    ┌─ cancel ≥24h ──────────────► REFUNDED (100%, auto)
                    │
CREATED ─pay─► PAID ─┼─ cancel <24h ─► RESCHEDULE_CREDIT (one use, 30d; →REFUNDED if no slot)
(in-hours: auto)    │
(off-hours: see §2a)└─ hold ─► CONFIRMED ─remind(T-15)─► LOBBY ─both join─► IN_CALL
                                                              │
   IN_CALL ─┬─ completes ──────────────► COMPLETED ──► SPLIT_PAID
            ├─ +extension ─────────────► COMPLETED (base+ext one settlement)
            ├─ celeb no-show (+5:00) ──► REFUNDED (100%, auto) + pickup-rate hit
            ├─ fan no-show (window end)► COMPLETED (celeb paid in full)
            ├─ conduct kill ───────────► FORFEITED (fan pays, celeb paid, ban)
            ├─ report filed ───────────► PAYOUT_HELD → T&S review → REFUNDED | SPLIT_PAID
            └─ platform tech fault ────► REFUNDED (100%) + celeb paid (platform eats it)

No-show thresholds (D2): celeb no-show fires at +5:00 past start; fan no-show fires at the scheduled window end. Both printed in the cancel policy.

Fair timer (D2): protected from the OTHER party's lateness, never your own. Celeb late → timer waits until both in → fan gets full duration → later calls drift (buffers absorb). Fan late → clock runs, 60-sec grace, then they eat it; call still ends at scheduled end.

2a. Off-hours requests (D3)

Booking outside standing hours: authorize (not capture) → fan sees PENDING → celeb accepts within min(24h from request, 24h before slot) → capture + confirm. Expire/decline → release authorization, notify fan, $0.

2b. Partial call / tech failure (D5)

Platform fault (infra/room dies): fan 100% refund, celeb paid in full, platform eats.
Connection fault, <50% of paid time delivered: free rebook (keeps GMV).
Call fine, recording lost: call stands + auto free 5-min credit to fan.

3. Scheduling (D1) — per-service grid

A celeb's availability is standing weekly hours (e.g. Tue 7–9 PM, Sat 2–4 PM) set in their home timezone, plus optional one-time drops (both draw from ONE calendar — no double-booking).
Fan picks a service first (5/10/20-min, celeb-priced), then sees a grid of open start times at that service's interval (5-min service → 7:00/7:05/7:10; 10-min → 7:00/7:10/7:20).
A booked call crosses its time out on every service's grid (shared calendar).
Auto-accept inside standing hours (instant confirm); anything outside = off-hours request (§2a).
Store all times UTC, display in each viewer's local tz; a tz library handles DST so the 24h deadline can't drift.

4. Recording & retention (D6)

Every call recorded (LiveKit egress → R2, MP4/AAC). Both parties consent: fan at checkout, celeb at go-live (onboarding) — add this consent moment.
Fan: personal downloaded copy is theirs forever; the stream/re-download link lives 90 days.
Celeb: archive persists while the account is active (cold storage); 90-day export grace on account close.
Platform moderation copy: 90 days, then purged unless a T&S case is open.
In-call: red REC chip is the consent disclosure. Report button both sides.

5. Identity — phone number = account

Number does five jobs: SMS delivery (the ring), zero-friction identity (no signup wall), celeb verification (OTP against the manager-registered number mints the ✓), ban anchor, and the web↔app bridge (book/claim on web → install app → type number → everything appears).

Numbers are never shared between parties — platform is the switchboard; all calls happen in-app/in-browser. Copy law: *"All calls happen in the Pay Phone app. Dre can't call you, you can't call him."* + *"So he can text you when new times open. Unsubscribe anytime."*
Email captured too = recovery + receipts/recording delivery.
New-device OTP also requires email (or card last-4) to block recycled-number takeover.
Web-number-A / app-number-B: "Find my booking" merge path.
Manager permissions (D-#68): CAN edit menu/hours/drops, view roster stats, message. CANNOT (without per-action celeb consent) cancel bookings, change payout bank, export fan PII. Payouts always land in the celeb's own Stripe.

6. Trust & Safety

Real-time frame sampling (Hive) + audio→text classifier on a server bot participant. High-confidence NSFW → blur/black + kill in seconds. Report (either side) → PAYOUT_HELD → human review with recording + transcript + join log + spender history → refund/forfeit/warn/ban (reason-coded). 2-hour SLA. Conduct kill: fan forfeits, celeb paid, ban. 18+ only (ToS); App Store rating 17+ (Apple's max); 18+ attestation at checkout.

7. The screens (each links to its approved mockup)

Celeb claim (all web until live): journey S1–S7d — invite text → claim → OTP verify → menu → hours+earnings hook → Stripe Connect → live + QR → App Store bridge → first open (zero re-entry).

Celeb app (4 tabs): app-proto-v2 — Today (next call + day plan) · Hours (weekly + menu + auto-accept) · Earnings (per-call payouts, dated sessions) · More (Audience export, Archive, payouts, settings, celeb recording consent).

Fan web booking: site/ — profile → per-service grid → contact → Apple Pay/card → confirmed → SMS → lobby → call → +5 extension → rate → recording.

Fan app: journey S24–S31 — two-door welcome → number → "your bookings appeared" → notifications → pick payphones → My Payphones home → Booked → You.

P1 (new): mockups/p1-screens — report/refund (R1–R3) + web my-bookings (B1–B4).

Admin: mockups/v4/admin — Today (KPIs+feed) · Lines/roster + drill-in · Trust&Safety case view.

Emails E1–E6: mockups/v4/emails — celeb live, celeb booking, fan confirm, T-15, recording ready, refund.

Design system: mockups/design-guide — tokens, type, icons (no emoji), copy law 7.1–7.4.

8. Build order (recommended)

Foundations: phone-OTP auth, Stripe Connect onboarding, the booking state machine (§2) as a tested pure module (mirror the TextingParents ledger discipline — one DB, truth-layer tests recomputing every number a user sees).
Celeb claim → live (web) so supply can be onboarded.
Fan web booking → payment → confirmation. Real Stripe test-mode end to end.
The call: LiveKit room, fair timer, recording egress, in-call report.
Notifications: Twilio SMS (confirm, T-15, drops) + push.
The apps (Expo) wrapping the above; My Payphones / Today.
Admin + T&S queue.
Emails (Resend), then the moderation layer (Hive) before any external talent.

Verification gate (per the founder's standing rule): every number a user sees gets a test recomputing it from the source store; drive each flow end-to-end and observe behavior, not just green tests; signed-in boot smoke on iOS sim + Android emulator before any build ships.

9. Open, non-code, founder-only blockers

⚠️ Register the domain (joinpayphone.com still shows unregistered).
Entity + D-U-N-S, Apple Developer (Org), Stripe, LiveKit, Twilio, Resend accounts.
Talent agreement (carries the reserve, rev-share, extension terms, taxes) — needs counsel.
Terms + Privacy are draft v1 — counsel review before public launch (two-party recording consent flagged).
The first manager pitch — the artifact that turns 10 managers into supply. Ready to write.

10. Deferred to v1.1 (not in launch)

Paid membership / paid-follow (D7 — free follow at launch), sold-out waitlist, celeb-rates-fan, account-deletion self-serve, manager bulk-onboarding tooling, celeb archive bulk export.