Whop × Spencer Agent

Payout Integration Guide

Replace PayPal Payouts with Whop’s global treasury — 180+ countries, crypto, ACH, wire. Runs side-by-side with PayPal. No rip-and-replace, no new dependencies.

PayPal Payouts → Whop Transfers FastAPI + Modal stays Internal ledger stays No new dependencies

Start Here — Drop This Into Your Repo

This file gives Cursor and Claude Code full context about your Whop migration. Every file path, schema change, and Python code example — ready to implement.

Save as CLAUDE.md in your project root. Open Cursor. Say “implement the Whop migration.”

Replace PayPal Payouts with Whop transfers in the contracted-ai codebase. Key files: utils/paypal/send_paypal_payout.py (replace with utils/whop/client.py), routes/post_my_cashout.py (add provider routing), web/src/pages/earnings.tsx (add Whop payout UI). Add provider column to payout_methods table, add whop_webhook_events table. Create webhook handler at routes/post_whop_webhook.py. Use PAYOUT_PROVIDER env var for global routing, payout_methods.provider for per-creator override. PayPal stays as default until full rollout. See CLAUDE.md for complete implementation with all Python code examples.

⚙ Rollout Strategy

Whop runs alongside PayPal in production. No staging environment needed, no new dependencies. Routing is controlled by an env var with per-creator override.

ℹ
PAYOUT_PROVIDER env var defaults to "paypal". Per-creator override: payout_methods.provider column. All routing lives in routes/post_my_cashout.py — one check, not scattered across files.
1

Build

Whop client, webhook controller, migration, both flow paths. PayPal stays default. Deploy with zero behavior change.

2

Internal Test

Set payout_methods.provider to "whop" on a test creator. Cash out with real money internally.

3

Small Cohort

Enable Whop for 5–10 trusted creators. Verify transfer parity, webhook delivery, and withdrawal timing.

4

Full Rollout

Flip PAYOUT_PROVIDER=whop globally. PayPal path stays in code as fallback until you’re confident.

⚡ Money Flow

How funds move from Spencer Agent to creators via Whop.

Creator Cashout

Platform Spencer Agent
→
Top-up Whop Balance
→
Transfer Creator Wallet
→
Withdrawal Bank / Crypto / PayPal

Replaces send_paypal_payout() in utils/paypal/send_paypal_payout.py. Cashout triggered from routes/post_my_cashout.py.

Credit Pull-back (Clawback)

Creator Whop Wallet
→
Transfer Reverse Transfer
→
Platform Spencer Agent

New capability — pull funds back from creator wallets for evaluation/penalties. Not possible with PayPal today.

□ Your Code → Whop

How your existing schemas and modules map to Whop. These are the columns that get added.

Your SchemaFileWhop EntityNew Columns
uploaders db/db.neon.contracted/schema.sql Company (connected account) — linked via payout_methods
payout_methods db/db.neon.contracted/schema.sql Payout Method + Company provider TEXT, whop_company_id TEXT
payouts db/db.neon.contracted/schema.sql Transfer (ctt_xxx) provider TEXT
credits db/db.neon.contracted/schema.sql — No changes
New table migration Webhook idempotency whop_webhook_events (event_id, event_type, processed_at)

▣ What Changes

Side-by-side: the calls you have today vs. the Whop equivalents.

PayPal (Today)

  • POST /v1/oauth2/token — get access token
  • POST /v1/payments/payouts — send payout to email
  • No webhooks — status via HTTP response
  • PayPal email only — no bank, no crypto
  • No clawback capability

Whop (After)

  • POST /companies — create creator account
  • POST /transfers — send payout to wallet
  • Webhooks for transfer + withdrawal status
  • 180+ countries: bank, crypto, PayPal, wire
  • Reverse transfers for clawbacks

⚡ Webhook Events

PayPal has no webhooks in your current setup. Whop adds real-time status tracking — this is an upgrade.

PayPal (Today)Whop EventWhat Happens
Nonepayment.succeededPlatform top-up confirmed
Nonepayment.failedPlatform top-up failed — alert ops
Nonetransfer.completedCashout transfer to creator confirmed
Nonewithdrawal.completedCreator withdrew to bank/crypto
Nonewithdrawal.failedCreator withdrawal failed — evaluate re-credit
Nonecompany.createdCreator connected account confirmed
ℹ
Whop webhook handler at /webhooks/whop is a new endpoint. PayPal had no webhook listener — this gives you real-time payout status for the first time.

▣ Architecture

Where Whop fits. Orange is new, green stays unchanged. Both providers coexist.

                     ┌──────────────────────┐
                     │ earnings.tsx (UI)  │
                     └─────────┬────────────┘
                              │
                     ┌─────────┴────────────┐
                     │ POST /me/cashout   │
                     │ get_payout_provider() │
                     └────┬─────────────┬────┘
                          │             │
              provider=   │             │   provider=
              "paypal"    │             │   "whop"
                          │             │
               ┌───────┴──┐   ┌────┴───────┐
               │ PayPal    │   │ Whop API    │
               │ Payouts   │   │ /transfers  │
               └─────┬────┘   └────┬───────┘
                     │             │
                     │        ┌───┴───────┐
                     │        │ Creator     │
                     │        │ Whop Wallet │
                     │        └────┬───────┘
                     │             │
               ┌─────┴─────────┴────┐
               │  Creator’s bank /    │
               │  crypto / PayPal     │
               └────────────────────┘

⏰ Timeline

Live by April 7. PayPal stays live the entire time.

Day 1–2
Build
  • Whop client + webhook controller
  • Database migration (3 columns + 1 table)
  • Both flow paths
  • Deploy — PayPal still default
Day 3–4
Internal Test
  • Enable Whop on test creator
  • Real money, real webhooks
  • Test clawback flow
Day 5–6
Small Cohort
  • 5–10 trusted creators
  • Transfer parity confirmed
  • Withdrawal timing validated
Day 7
Full Rollout
  • Flip env var to “whop”
  • PayPal path stays as fallback
  • First live dollar via Whop

✓ What Stays the Same

Most of your stack is unchanged. Whop replaces only the payout execution layer.

✓ FastAPI + Modal.com
✓ PostgreSQL on Neon
✓ React 19 + Vite 6
✓ Tailwind CSS 4
✓ Capacitor (iOS/Android)
✓ Credits ledger
✓ Balance tracking
✓ Auth (email OTP + JWT)
✓ Admin dashboard
✓ Cashout policy ($5 min)
✓ No new dependencies
✓ Cloudflare Workers (FE)
~ earnings.tsx (new payout UI)
~ payout_methods (2 new cols)
✓
Bottom line: Your internal ledger (credits, balance, tiers), auth system, admin tools, and entire frontend framework are untouched. PayPal code stays in the repo as fallback. No new dependencies added — the Whop client uses Python’s built-in urllib.