Read through each change and check it off. Progress is saved on this device.
0/23
reviewed
All fiat payments go through Stripe Checkout
Buyers pay with cards via Stripe Checkout sessions. The platform collects the full gross amount, and the seller's net is released via a Stripe Connect Transfer after the 48h inspection window passes. Stripe is the sole processor for all monetary (USD) transactions.
finalize-order issues Stripe Connect Transfers to sellers
When the inspection window expires on a fiat order, finalize-order creates a Stripe Transfer of the seller_net amount to the seller's Connect account. The transfer_id is recorded on the Order. No in-house balance is used for fiat payouts — Stripe handles it end-to-end.
Storefront upgrades and token lots billed via Stripe
Monthly subscriptions (storefront tiers, AI design assistant, token lots) and one-time purchases (token lots, ad promotions, auction boosts) all use Stripe Checkout. The stripe-webhook backend function processes invoice.paid and checkout.session.completed events to drip tokens, credits, and extend promotions.
Dispute refunds processed through Stripe
When an order is auto-refunded via process-dispute-refund, fiat payments receive a full Stripe Refund (payment_intent refund). The buyer gets their money back through Stripe, not through an in-house balance.
TokenTransaction entity logs all token movements
A database entity records every token movement platform-wide — slot spins, AI design, storefront upgrades, marketplace purchases, sales, refunds, transfers, and deposits. Each record captures the user, action type, tokens consumed (negative = credit), bet/payout for spins, and the linked order or counterparty.
Token economy rate: 1 token = $0.40 USD (stable, non-dynamic)
Shared configuration in src/lib/tokenEconomy.js and base44/shared/tokenEconomy.js establishes a STABLE trade value of $0.40 per token — not a dynamic or floating rate. This keeps slot spins approachable ($0.40/spin vs $1.00) while maintaining a clean peg for marketplace settlement. The rate is used consistently across checkout, payouts, the slot machine, and AI design.
Token pack amounts recalculated for $0.40 rate
Token packs use existing Stripe prices but deliver tokens at the new rate: Small ($2.99 → 8 tokens ≈ $0.37/token, ≤ listing fee), Medium ($9.99 → 25 tokens = $0.40/token), Large ($19.99 → 50 tokens = $0.40/token). The create-token-checkout function maps lot_id to the new token amounts; the Stripe webhook credits metadata.token_amount.
Processing fee applies only to marketplace sales, not utility spending
The in-house token processing fee (2.9% + $0.30 equivalent) is scoped to marketplace purchases in create-order only. Slot spins, storefront upgrades, AI design, and other in-platform utility spending do NOT incur this fee — those are frictionless entertainment/utility actions. The fee exists solely to maintain parity between fiat (Stripe) and token payment rails on actual item sales.
Token payments use in-house escrow (no Stripe)
When a buyer pays with tokens, create-order validates their combined balance (UserProfile + Storefront), deducts the exact token amount, and holds it in escrow (token_escrow_held=true). No Stripe session is created for token orders — the entire flow is in-house.
finalize-order credits seller tokens at $0.40 rate
On a token-paid order, the seller's USD net (seller_net) is converted to tokens at the $0.40/token rate via usdToTokens(), then credited to the seller's Storefront (or UserProfile). Sale-proceeding tokens are cash-out eligible (cash_out_balance is incremented); the 5-token loyalty bonus is NOT eligible (utility credit). A TokenTransaction logs the credit with source_type: 'marketplace_sale'. No Stripe Transfer is created — the payout is in-house tokens.
Dispute refunds return escrowed tokens in-house
If a token-paid order is disputed and auto-refunded, the buyer's escrowed tokens are returned to their UserProfile balance and a marketplace_refund TokenTransaction is logged. No Stripe refund is needed — tokens move back in-house.
Token Store purchases are funded via Stripe
Sellers buy token lots through Stripe Checkout (Small/Medium/Large at $2.99/$9.99/$19.99). At the $0.40/token rate, these deliver 8/25/50 tokens respectively. The stripe-webhook function credits the purchased tokens to the Storefront token_balance + cash_out_balance, increments purchased_tokens_ever (global jackpot eligibility), and logs a TokenTransaction with source_type: 'fiat_purchase' and cash_out_eligible: true.
In-house token processing fee (2.9% + $0.30 equivalent)
Token (RRT) payments don't go through Stripe, so no actual card-processing fee is incurred. To maintain fee parity between fiat and token rails, create-order now calculates a calculateTokenProcessingFee (same 2.9% + $0.30 rate) and deducts it from the seller's net on token orders. The platform captures this amount as revenue instead of paying it to Stripe — stored on the Order as token_processing_fee. The seller's net is the same whether the buyer pays in USD or RRT, ensuring the platform realizes identical margins on both rails.
Dashboard shows combined token balance
The seller dashboard stat grid includes a 'Token balance' card showing the sum of the user's UserProfile and Storefront token balances. The TokenConsumptionTable (collapsible) shows a usage breakdown, and the admin-only TokenUsageChart visualizes platform-wide daily consumption.
cash_out_balance tracks eligible tokens separately from token_balance
Both Storefront and UserProfile entities now have a cash_out_balance field that tracks the subset of token_balance eligible for cash-out. Eligible sources: fiat purchases (Stripe), marketplace sale proceeds, AND slot winnings (backed by the fiat reserve). Bonuses and utility credits that never had fiat backing are NOT eligible. At cash-out time, the eligible amount is min(cash_out_balance, token_balance) to guard against over-spending.
TokenTransaction logs source_type + cash_out_eligible for every movement
The TokenTransaction entity now records source_type (fiat_purchase, marketplace_sale, slot_win, bonus, utility_spend, marketplace_spend, cashout, refund) and cash_out_eligible (boolean) on every token movement. This provides a complete audit trail showing the origin of every token — essential for verifying cash-out eligibility and keeping token purchase funds independent of platform fee revenue.
token-cashout backend function converts eligible tokens to cash
A new backend function (base44/functions/token-cashout) lets users convert eligible tokens back to USD at any time. It computes the eligible balance from Storefront + UserProfile, applies a 2% exchange fee (CASHOUT_FEE_RATE), and issues a Stripe Transfer to the seller's Connect account. The deduction is logged as a TokenTransaction with action_type: 'token_cashout'. Requires a Stripe Connect account — if none is configured, the function returns an error directing the user to set one up.
2% exchange fee applies only to cash-out, not utility spending
The CASHOUT_FEE_RATE (2%) is charged ONLY when a user converts tokens back to cash via the token-cashout function. It does NOT apply to slot spins, storefront upgrades, AI design, marketplace purchases, or any other in-platform utility spending. This keeps the in-game economy frictionless while capturing a fair exchange fee on high-value cash withdrawals.
Token purchase funds are kept independent of fee revenue (closed-loop reserve)
When a user buys tokens via Stripe, the funds are tracked as a liability (cash_out_balance) — not realized as platform revenue. The closed-loop reserve model backs ALL cashable tokens (purchases, marketplace sales, AND slot winnings) with this fiat reserve. The house edge (10–25% per spin tier + 7% pool contributions) mathematically guarantees the reserve always exceeds outstanding liability. Revenue is recognized on upgrades (storefront revenue), marketplace fees (platform fee), and cash-out (2% exchange fee). A 1,000,000-transaction Monte Carlo simulation validated the model: realized RTP 87.78%, peak reserve liability $81,249 vs. $161,665 fiat collected (50% reserve ratio), zero shortfall detected, and a full bank-run scenario survived with $82,003 remaining in reserve.
Slot winnings are now cash-out eligible (backed by the fiat reserve)
play-slot now credits winnings to cash_out_balance alongside token_balance, and logs them as source_type: 'slot_win' with cash_out_eligible: true. Because every token purchased via Stripe deposited $0.40 into the platform reserve, and the house edge burns more tokens than the reserve needs to cover, winnings are fully backed. The bet is deducted from cash_out_balance first (up to available), then winnings are credited back as cashable. The TokenTransaction ledger provides a complete audit trail of every token's origin and cashability.
CheckoutButton supports payment method selection
The checkout UI loads the buyer's combined token balance and presents a payment method selector. Buyers can pay with tokens if their balance covers the purchase, or fall back to Stripe (fiat). Crypto fields exist on the Order entity but crypto is deferred for now.
Combined balance loading (UserProfile + Storefront)
Both the CheckoutButton and Dashboard load tokens from both the buyer's UserProfile and their Storefront, since Token Store purchases credit the Storefront while marketplace sale proceeds may go to either. The create-order backend re-validates server-side.
Order entity extended with payment_method field
The Order entity now stores payment_method (fiat/token/crypto), token_amount (tokens charged), token_escrow_held (escrow status), and crypto fields for future use. The finalize-order and process-dispute-refund functions branch on payment_method to route each type correctly.
