feat(payments): manual payout tracking for single-account providers (#493) (#503)

PayPal, Binance Pay (merchant), and Lemon Squeezy settle 100% of every sale
into the platform's own account with no automatic split (unlike Stripe
Connect or the on-chain Solana split) — the school's share has to be paid
out manually, and the previously dead `payouts` table never recorded that.

Adds /platform/payouts (metric cards + by-school table, mirroring the
existing platform admin page pattern) backed by a pure computeOwedBalances()
function: gross collected per platform-settled provider, minus manual
payouts already recorded, per tenant. `ProviderCapabilities.settlesToPlatformAccount`
is the single source of truth for which providers route through this path.

Live-verified against a real PayPal sale locally (issue #493 epic notes:
$10 sale -> $8.00 owed at 80% split -> Mark as Paid -> $0.00, payouts row
inserted correctly). Known gaps in the money math (revenue split not
time-sliced, no currency grouping, no refund clawback, no overpayment
guardrail) are tracked as epic #493's Phase 2 sub-issues (#496-#499) and
addressed in follow-up commits; deploying the migration to cloud is #500.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: guillermoscript

app/[locale]/platform/payouts/page.tsx

@@ -0,0 +1,151 @@
+import { getPayoutsOwed } from '@/app/actions/platform/payouts'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+import { MarkPayoutPaidDialog } from '@/components/platform/mark-payout-paid-dialog'
+import {
+  IconCoin,
+  IconReportMoney,
+  IconWalletOff,
+} from '@tabler/icons-react'
+
+const usd = (n: number) =>
+  new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(n ?? 0)
+
+const PROVIDER_LABEL: Record<string, string> = {
+  paypal: 'PayPal',
+  binance: 'Binance Pay',
+  lemonsqueezy: 'Lemon Squeezy',
+}
+
+export default async function PlatformPayoutsPage() {
+  const owed = await getPayoutsOwed()
+
+  const totalOwed = owed.reduce((sum, t) => sum + t.netOwed, 0)
+  const totalCollected = owed.reduce((sum, t) => sum + t.grossCollected, 0)
+  const totalPaidOut = owed.reduce((sum, t) => sum + t.alreadyPaid, 0)
+  const schoolsOwed = owed.filter((t) => t.netOwed > 0).length
+
+  const metricCards = [
+    {
+      title: 'Currently Owed',
+      value: usd(totalOwed),
+      sub: `${schoolsOwed} school${schoolsOwed === 1 ? '' : 's'} awaiting payout`,
+      icon: IconWalletOff,
+      bg: 'bg-amber-50 dark:bg-amber-950/40',
+      iconColor: 'text-amber-600 dark:text-amber-400',
+    },
+    {
+      title: 'Collected (single-account providers)',
+      value: usd(totalCollected),
+      sub: 'PayPal, Binance Pay, Lemon Squeezy — 100% lands in your account',
+      icon: IconCoin,
+      bg: 'bg-blue-50 dark:bg-blue-950/40',
+      iconColor: 'text-blue-600 dark:text-blue-400',
+    },
+    {
+      title: 'Paid Out (all time)',
+      value: usd(totalPaidOut),
+      sub: 'Manually recorded payouts to schools',
+      icon: IconReportMoney,
+      bg: 'bg-emerald-50 dark:bg-emerald-950/40',
+      iconColor: 'text-emerald-600 dark:text-emerald-400',
+    },
+  ]
+
+  return (
+    <main className="flex-1 px-4 py-6 sm:px-6 lg:px-8" data-testid="platform-payouts">
+      <div className="mb-8">
+        <h1 className="text-2xl font-bold tracking-tight">Payouts</h1>
+        <p className="text-sm text-muted-foreground mt-1">
+          PayPal, Binance Pay, and Lemon Squeezy don&apos;t split automatically — 100% of every sale
+          lands in your account. This is what you owe each school back, based on their revenue split.
+        </p>
+      </div>
+
+      <div className="mb-8 grid gap-3 sm:grid-cols-3" data-testid="payouts-metrics">
+        {metricCards.map((card) => (
+          <Card key={card.title} className="relative overflow-hidden">
+            <CardContent className="p-5">
+              <div className="flex items-start justify-between">
+                <div className="min-w-0 flex-1">
+                  <p className="text-[11px] font-medium uppercase tracking-wider text-muted-foreground">
+                    {card.title}
+                  </p>
+                  <p className="mt-2 text-2xl font-bold tracking-tight tabular-nums" data-testid="metric-value">
+                    {card.value}
+                  </p>
+                  <p className="mt-1 text-[11px] text-muted-foreground/70">{card.sub}</p>
+                </div>
+                <div className={`flex h-9 w-9 shrink-0 items-center justify-center rounded-lg ${card.bg}`}>
+                  <card.icon className={`h-[18px] w-[18px] ${card.iconColor}`} strokeWidth={1.75} />
+                </div>
+              </div>
+            </CardContent>
+          </Card>
+        ))}
+      </div>
+
+      <Card data-testid="payouts-by-tenant">
+        <CardHeader>
+          <CardTitle>By school</CardTitle>
+        </CardHeader>
+        <CardContent>
+          {owed.length === 0 ? (
+            <p className="text-muted-foreground text-sm">No schools yet.</p>
+          ) : (
+            <div className="overflow-x-auto">
+              <table className="w-full text-sm">
+                <thead>
+                  <tr className="border-b text-left text-[11px] uppercase tracking-wider text-muted-foreground">
+                    <th className="pb-2 font-medium">School</th>
+                    <th className="pb-2 font-medium">Providers</th>
+                    <th className="pb-2 text-right font-medium">Collected</th>
+                    <th className="pb-2 text-right font-medium">School %</th>
+                    <th className="pb-2 text-right font-medium">Paid so far</th>
+                    <th className="pb-2 text-right font-medium">Owed</th>
+                    <th className="pb-2 text-right font-medium"></th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {owed.map((t) => (
+                    <tr key={t.tenantId} className="border-b last:border-0">
+                      <td className="py-2.5 font-medium">{t.tenantName}</td>
+                      <td className="py-2.5 text-muted-foreground">
+                        {Object.keys(t.byProvider).length === 0
+                          ? '—'
+                          : Object.keys(t.byProvider).map((p) => PROVIDER_LABEL[p] ?? p).join(', ')}
+                      </td>
+                      <td className="py-2.5 text-right tabular-nums">{usd(t.grossCollected)}</td>
+                      <td className="py-2.5 text-right tabular-nums text-muted-foreground">
+                        {t.schoolPercentage}%
+                      </td>
+                      <td className="py-2.5 text-right tabular-nums text-muted-foreground">
+                        {usd(t.alreadyPaid)}
+                      </td>
+                      <td className="py-2.5 text-right tabular-nums font-medium text-amber-600 dark:text-amber-400">
+                        {usd(t.netOwed)}
+                      </td>
+                      <td className="py-2.5 text-right">
+                        <MarkPayoutPaidDialog
+                          tenantId={t.tenantId}
+                          tenantName={t.tenantName}
+                          netOwed={t.netOwed}
+                        />
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+
+      <p className="mt-6 text-[11px] text-muted-foreground/70">
+        Stripe and Solana sales already split automatically and never appear here. Binance Pay
+        (personal account) and manual/offline sales settle straight to the school and also never
+        appear here — only PayPal, Binance Pay (merchant), and Lemon Squeezy do, since those settle
+        100% into your account today.
+      </p>
+    </main>
+  )
+}

app/actions/platform/payouts.ts

@@ -0,0 +1,75 @@
+'use server'
+
+import { createClient } from '@/lib/supabase/server'
+import { createAdminClient } from '@/lib/supabase/admin'
+import { isSuperAdmin } from '@/lib/supabase/get-user-role'
+import { revalidatePath } from 'next/cache'
+import { getCurrentUserId } from '@/lib/supabase/tenant'
+import { PROVIDER_CAPABILITIES, type PaymentProvider } from '@/lib/payments/types'
+import { computeOwedBalances, type TenantOwed } from '@/lib/payments/payouts-owed'
+
+async function verifySuperAdmin() {
+  const supabase = await createClient()
+  const userId = await getCurrentUserId()
+  if (!userId) throw new Error('Not authenticated')
+  if (!(await isSuperAdmin())) throw new Error('Super admin only')
+  return userId
+}
+
+const PLATFORM_SETTLED_PROVIDERS = (Object.keys(PROVIDER_CAPABILITIES) as PaymentProvider[]).filter(
+  (provider) => PROVIDER_CAPABILITIES[provider].settlesToPlatformAccount
+)
+
+const DEFAULT_SCHOOL_PERCENTAGE = 80
+
+export async function getPayoutsOwed(): Promise<TenantOwed[]> {
+  await verifySuperAdmin()
+  const admin = createAdminClient()
+
+  const [{ data: tenants }, { data: splits }, { data: txns }, { data: paid }] = await Promise.all([
+    admin.from('tenants').select('id, name'),
+    admin.from('revenue_splits').select('tenant_id, school_percentage'),
+    admin
+      .from('transactions')
+      .select('tenant_id, payment_provider, amount')
+      .eq('status', 'successful')
+      .in('payment_provider', PLATFORM_SETTLED_PROVIDERS),
+    admin.from('payouts').select('tenant_id, amount').eq('payout_method', 'manual').eq('status', 'paid'),
+  ])
+
+  const schoolPercentageByTenant = new Map(
+    (splits || []).map((s) => [s.tenant_id, s.school_percentage as number])
+  )
+
+  return computeOwedBalances(
+    (tenants || []).map((t) => ({
+      tenantId: t.id,
+      tenantName: t.name,
+      schoolPercentage: schoolPercentageByTenant.get(t.id) ?? DEFAULT_SCHOOL_PERCENTAGE,
+    })),
+    (txns || [])
+      .filter((t) => t.tenant_id && t.payment_provider && t.amount != null)
+      .map((t) => ({ tenantId: t.tenant_id as string, paymentProvider: t.payment_provider as string, amount: t.amount as number })),
+    (paid || []).map((p) => ({ tenantId: p.tenant_id, amount: p.amount }))
+  )
+}
+
+export async function markPayoutPaid(tenantId: string, amount: number, note?: string) {
+  const userId = await verifySuperAdmin()
+  if (!(amount > 0)) throw new Error('Amount must be positive')
+
+  const admin = createAdminClient()
+  const { error } = await admin.from('payouts').insert({
+    tenant_id: tenantId,
+    amount,
+    currency: 'usd',
+    status: 'paid',
+    payout_method: 'manual',
+    paid_at: new Date().toISOString(),
+    recorded_by: userId,
+    note: note || null,
+  })
+  if (error) throw new Error(error.message)
+
+  revalidatePath('/platform/payouts')
+}

components/platform-sidebar.tsx

@@ -14,6 +14,7 @@ import {
   IconSchool,
   IconSettings,
   IconUsers,
+  IconWallet,
 } from "@tabler/icons-react"
 import {
   Sidebar,
@@ -49,6 +50,7 @@ export function PlatformSidebar({ pendingBillingCount = 0, atRiskCount = 0, ...p
     { title: "Overview", href: "/platform", icon: IconChartBar },
     { title: "Tenants", href: "/platform/tenants", icon: IconSchool },
     { title: "Revenue", href: "/platform/revenue", icon: IconReportMoney },
+    { title: "Payouts", href: "/platform/payouts", icon: IconWallet },
     { title: "Billing", href: "/platform/billing", icon: IconCreditCard, badge: pendingBillingCount },
     { title: "Billing Health", href: "/platform/billing-health", icon: IconAlertTriangle, badge: atRiskCount },
     { title: "Plans", href: "/platform/plans", icon: IconBuildingStore },

components/platform/mark-payout-paid-dialog.tsx

@@ -0,0 +1,104 @@
+"use client"
+
+import { useState } from "react"
+import { useRouter } from "next/navigation"
+import { toast } from "sonner"
+import { Button } from "@/components/ui/button"
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+import { Textarea } from "@/components/ui/textarea"
+import { markPayoutPaid } from "@/app/actions/platform/payouts"
+
+interface Props {
+  tenantId: string
+  tenantName: string
+  netOwed: number
+}
+
+export function MarkPayoutPaidDialog({ tenantId, tenantName, netOwed }: Props) {
+  const router = useRouter()
+  const [open, setOpen] = useState(false)
+  const [amount, setAmount] = useState(netOwed.toFixed(2))
+  const [note, setNote] = useState('')
+  const [loading, setLoading] = useState(false)
+
+  async function handleConfirm() {
+    const parsed = Number(amount)
+    if (!(parsed > 0)) {
+      toast.error('Enter a positive amount')
+      return
+    }
+    setLoading(true)
+    try {
+      await markPayoutPaid(tenantId, parsed, note.trim() || undefined)
+      toast.success(`Recorded $${parsed.toFixed(2)} paid to ${tenantName}`)
+      setOpen(false)
+      setNote('')
+      router.refresh()
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : 'Failed to record payout')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <>
+      <Button
+        size="sm"
+        variant="outline"
+        onClick={() => setOpen(true)}
+        disabled={netOwed <= 0}
+        data-testid="mark-paid-btn"
+      >
+        Mark as Paid
+      </Button>
+
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent data-testid="mark-paid-dialog">
+          <DialogHeader>
+            <DialogTitle>Record payout to {tenantName}</DialogTitle>
+          </DialogHeader>
+          <div className="space-y-3 py-2">
+            <div className="space-y-1.5">
+              <Label htmlFor="payout-amount">Amount paid (USD)</Label>
+              <Input
+                id="payout-amount"
+                type="number"
+                step="0.01"
+                min="0"
+                value={amount}
+                onChange={(e) => setAmount(e.target.value)}
+                data-testid="mark-paid-amount-input"
+              />
+            </div>
+            <div className="space-y-1.5">
+              <Label htmlFor="payout-note">Note (optional)</Label>
+              <Textarea
+                id="payout-note"
+                placeholder="e.g. wire reference, date sent…"
+                value={note}
+                onChange={(e) => setNote(e.target.value)}
+                rows={2}
+                data-testid="mark-paid-note-input"
+              />
+            </div>
+          </div>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
+            <Button onClick={handleConfirm} disabled={loading} data-testid="confirm-mark-paid-btn">
+              {loading ? 'Recording…' : 'Record Payout'}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  )
+}

lib/payments/binance-personal-provider.ts

@@ -99,6 +99,7 @@ export class BinancePersonalProvider implements IPaymentProvider {
     selfManagedPeriod: true,
     createsCatalog: false,
     supportsPlanChange: false,
+    settlesToPlatformAccount: false,
   }
 
   private readonly apiKey?: string

lib/payments/binance-provider.ts

@@ -68,6 +68,7 @@ export class BinancePayProvider implements IPaymentProvider {
     selfManagedPeriod: true,
     createsCatalog: false,
     supportsPlanChange: false,
+    settlesToPlatformAccount: true,
   }
 
   private readonly apiKey: string

lib/payments/lemonsqueezy-provider.ts

@@ -49,6 +49,7 @@ export class LemonSqueezyProvider implements IPaymentProvider {
     selfManagedPeriod: false,
     createsCatalog: false,
     supportsPlanChange: true,
+    settlesToPlatformAccount: true,
   }
 
   private readonly apiKey: string

lib/payments/manual-provider.ts

@@ -30,6 +30,7 @@ export class ManualPaymentProvider implements IPaymentProvider {
     selfManagedPeriod: true,
     createsCatalog: false,
     supportsPlanChange: false,
+    settlesToPlatformAccount: false,
   }
 
   convertAmount(amount: number, fromUnit: 'base' | 'major'): number {