pal-e-docs

Plan: Stripe Connect Payouts

plan-2026-02-25-stripe-connect-payouts Plan

plan completed
Project

Vision

A fully automated financial backend for Westside Basketball: all staff (coaches and owners) onboard as 1099 contractors via email invite, receive payouts through Stripe Connect, and get IRS-compliant 1099-NEC forms at year end — all managed through a self-hosted API on the Pal-E platform with no manual bookkeeping.

Projects & Repos Touched

Project/Repo Platform Role in this plan
westside-api (new) Forgejo New service: FastAPI backend for contractor onboarding, payouts, and admin
west-side-basketball GitHub May add admin link or contractor portal link to site
pal-e-services GitHub Add westside-api to k3s.tfvars for ArgoCD deployment

Context

Stripe is already live collecting tryout fees via Payment Links. Webhook fires to pal-e-billing. But there's no system for paying staff — it's all manual. All staff (coaches and owners) are 1099 independent contractors, which means:
  • No payroll tax withholding (contractors handle their own taxes)
  • 1099-NEC forms must be filed for anyone paid $600+ in a calendar year
  • Stripe Connect handles 1099 generation, IRS e-filing, and delivery to contractors ($2.99/form)
  • Non-profit status does NOT affect Stripe Connect setup — same system either way (confirmed in Phase 1 research)
What's already done:
  • ☑ Stripe account live with Payment Links and webhook
  • ☑ Stripe secrets stored at ~/secrets/stripe/
  • ☑ SendGrid API key available for emails
  • ☑ Financial Architecture documented in Notion (being migrated to pal-e-docs)
  • ☑ pal-e-docs browse frontend is publicly funneled — can share note links with Marcus directly
  • ☑ Non-profit research complete — recommendation: go 501(c)(3)
  • ☐ Stripe Connect not yet enabled on the account
  • ☐ EIN not yet obtained (needed to go live, not needed to build)

Previous Plan

None — first plan for this project.

Depends On

  • None — Phase 1 complete. Phase 2 has no blockers. Phase 3 code can be built now; going live needs EIN.

Decisions Made

Decision Rationale
Separate repo (westside-api) on Forgejo, not in the GitHub Pages repo API handles secrets, needs a backend runtime, follows service-onboarding-sop. Static site stays clean.
FastAPI + Python Stripe Python SDK is first-class. Consistent with other pal-e-services (pal-e-docs, pal-e-billing).
Stripe Connect with Express accounts Express accounts let Stripe handle identity verification, tax form collection, and bank/direct deposit setup. Minimal code on our side. Contractors get a Stripe-hosted onboarding flow.
Email-based contractor onboarding Admin triggers invite via API → contractor receives email with Stripe Connect onboarding link → once completed, they're payable.
All staff are 1099 contractors No W-2 employees. Owners (Lucas, Marcus) and all coaches go through the same Stripe Connect flow. Simplifies the system to one payment path.
No banking integration (no Mercury) Stripe Connect handles contractor payouts directly. Operational expenses paid from Stripe auto-payout to bank. No sub-account budgeting system needed.
1099 reporting via Stripe Connect Tax Reporting Stripe auto-generates and e-files 1099-NEC forms. $2.99/form. No manual IRS filing needed.
Non-profit (501(c)(3)) recommended Tax-deductible donations attract sponsors, grant eligibility, tax-exempt revenue. Doesn't affect Stripe Connect. Can start for-profit later as separate entity. Total setup cost ~$305.

Phases

Phase 1: Non-profit & Stripe Connect research ☑ COMPLETE

  • Slug: phase-2026-02-25-1-nonprofit-stripe-research
  • Goal: Determine whether non-profit status affects Stripe Connect setup, 1099 reporting, or contractor payout flow — produce a decision document and share it with Marcus via a live pal-e-docs link.
  • Owner: main session (research)
  • Status: COMPLETE (2026-02-26)
  • Deliverables:
  • Key findings:
  • Remaining: Marcus needs to review the note and confirm non-profit decision + get EIN (async, not blocking build)

Phase 2: Scaffold westside-api service ☐ NEXT

  • Slug: phase-2026-02-25-2-scaffold-westside-api
  • Goal: Create a deployable FastAPI service on Forgejo with Dockerfile, CI pipeline, and k8s manifests — no business logic yet, just the skeleton.
  • Owner: agent-dev (worktree)
  • Note: No blockers — can start immediately.
  • Steps:
  • Issue note: TBD (create when starting)

Phase 3: Stripe Connect contractor onboarding

  • Slug: phase-2026-02-25-3-contractor-onboarding
  • Goal: Admin can invite any contractor (coach or owner) by email; contractor completes Stripe Connect Express onboarding (including direct deposit / bank info); contractor account is stored and ready for payouts.
  • Owner: agent-dev (worktree)
  • Note: Code can be built and tested against Stripe test mode without EIN. Going live requires EIN.
  • Steps:
  • Issue note: TBD

Phase 4: Payout automation & 1099 reporting

  • Slug: phase-2026-02-25-4-payout-automation
  • Goal: Admin can trigger payouts to onboarded contractors; Stripe Connect handles 1099 tax reporting at year end.
  • Owner: agent-dev (worktree)
  • Steps:
  • Issue note: TBD

Key Files

Phase File Repo Change
1 <code>nonprofit-stripe-research</code> pal-e-docs Research note — DELIVERED
2 main.py westside-api FastAPI app with health endpoint
2 Dockerfile westside-api Python 3.12 container
2 .woodpecker.yaml westside-api CI pipeline
2 k8s/deployment.yaml westside-api K8s Deployment + Service
2 terraform/k3s.tfvars pal-e-services Add westside-api service entry
3 routers/contractors.py westside-api Contractor invite, list, refresh endpoints
3 routers/webhooks.py westside-api Stripe Connect webhook handler
3 models.py westside-api Contractor data model
4 routers/payouts.py westside-api Payout creation and history endpoints
4 models.py westside-api Payout data model

Verification

  • ☑ Phase 1: Research note live at https://pal-e-docs.tail5b443a.ts.net/browse/notes/nonprofit-stripe-research
  • ☐ Phase 2: curl https://westside-api.tail5b443a.ts.net/health returns 200
  • ☐ Phase 3: Invite a test contractor → they receive email → complete Stripe onboarding (including bank info) → status shows "active" in admin endpoint
  • ☐ Phase 4: Trigger a test payout to a connected account → transfer shows in Stripe Dashboard → contractor receives confirmation email

Next Plan Seeds

  • Player/Parent Registration — profile creation with photo uploads, player properties (height, grad class, position, school, local/travel preference), parent contact info. Likely adds endpoints to westside-api + MinIO for image storage.
  • Admin Dashboard — web UI for Marcus to manage contractors, view payouts, manage rosters. Could be a simple SPA or server-rendered pages in westside-api.
  • Contractor Agreements — formalized PDF contracts with e-signature (DocuSign API or similar). Currently using verbal/email agreement.