Stripe Connect Setup

Complete guide to configuring Stripe Connect for your beat marketplace.

What is Stripe Connect?

Stripe Connect allows you to facilitate payments between buyers and sellers without ever touching the money yourself. Beat makers receive payouts directly to their bank accounts, while you collect a platform fee.

Account Types

Beat Flow uses Express accounts:

• ✅ Stripe-hosted onboarding (no custom UI needed)
• ✅ Automatic KYC and identity verification
• ✅ Direct payouts to seller bank accounts
• ✅ No liability for chargebacks or fraud
• ✅ Stripe handles tax reporting (1099-K)

Step 1: Create Stripe Account

1. Go to stripe.com
2. Click "Start now" and create account
3. Complete business verification (required for live mode)
4. Add bank account for platform fee deposits

Step 2: Enable Stripe Connect

1. Log in to Stripe Dashboard
2. Go to Settings → Connect
3. Toggle "Enable Connect" to ON
4. That's it! No additional configuration needed for Express accounts

Step 3: Get API Keys

Test Mode (Development)

1. Go to Test Mode API Keys
2. Copy "Secret key" (starts with sk_test_)
3. Use this for development and testing

Live Mode (Production)

1. Go to Live Mode API Keys
2. Copy "Secret key" (starts with sk_live_)
3. Use this for production (ONLY after testing is complete)

Set Secret in Workers

cd /tmp/beatflow/workers

# For development (test mode)
npx wrangler secret put STRIPE_SECRET_KEY
# Enter: sk_test_...

# For production (live mode) - ONLY when ready to launch
npx wrangler secret put STRIPE_SECRET_KEY
# Enter: sk_live_...

Step 4: Configure Webhook Endpoint

Webhooks notify your Worker when payments complete, accounts update, etc.

Create Webhook (After Deploying Workers)

1. Deploy your Workers first:

   cd /tmp/beatflow/workers && npm run deploy

2. Go to Stripe Webhooks
3. Click "Add endpoint"
4. Endpoint URL:

   https://beatflow-api.terry-c67.workers.dev/api/webhooks/stripe

5. Listen to events: Select these 3 events:
   • checkout.session.completed - Payment successful
   • account.updated - Seller onboarding status changed
   • payment_intent.payment_failed - Payment failed
6. Click "Add endpoint"
7. Copy the "Signing secret" (starts with whsec_)

Set Webhook Secret

cd /tmp/beatflow/workers
npx wrangler secret put STRIPE_WEBHOOK_SECRET
# Enter: whsec_...

Understanding the Payment Flow

Destination Charges

Beat Flow uses destination charges where payments go directly to the seller, and you collect a platform fee:

Buyer pays $100
├─ Stripe fee (2.9% + 30¢): $3.20
├─ Platform fee (10%): $10.00
└─ Seller receives: $86.80

Payment Flow Diagram

1. Buyer clicks "Buy" → Worker creates Checkout session
2. Stripe charges buyer → Captures payment
3. Webhook fires → checkout.session.completed
4. Worker updates database → Marks transaction as paid, generates download token
5. Buyer gets download links → Time-limited R2 signed URLs
6. Stripe transfers funds → 90% to seller, 10% to you (minus Stripe fees)

Seller Onboarding Flow

How It Works

1. Seller clicks "Become a Seller" on your site
2. Worker calls POST /api/sellers/onboard
3. Worker creates Stripe Express account via API
4. Worker generates Stripe-hosted onboarding URL
5. Seller redirected to Stripe's onboarding form
6. Seller enters:
   • Bank account details
   • Identity verification (SSN, photo ID)
   • Tax information (W-9 or W-8)
   • Business details
7. Stripe verifies identity and bank account
8. Webhook fires → account.updated
9. Worker marks seller as onboarding_complete
10. Seller can now receive payouts!

Test Onboarding

In test mode, use these test values:

• SSN: 000-00-0000
• Bank Account: Use Stripe's test routing numbers
• Phone: Any 10-digit number
• DOB: Any date (18+ years ago)

See Stripe Connect Testing Guide for complete test data.

Monitoring & Management

Stripe Dashboard Sections

Webhook Status

Monitor webhook delivery in Stripe Dashboard:

• ✅ Success rate should be >99%
• ⚠️ Failed webhooks will retry automatically
• ❌ Repeated failures indicate Worker issues

Platform Fee Configuration

Platform fee is set in workers/wrangler.toml:

[vars]
PLATFORM_FEE_PERCENT = "10"  # 10% platform fee

Common fee structures:

• 5% - Low fee, high volume strategy
• 10% - Industry standard (Beat Flow default)
• 15% - Premium platform with added services
• 20% - High-touch, curated marketplace

Calculating Earnings

$100 beat sale at 10% platform fee:

Buyer pays:          $100.00
Stripe fee (2.9%+30¢): -$3.20
Platform fee (10%):   +$10.00
Seller receives:      $86.80

Your net earnings:    $10.00 - (10% of $3.20) = ~$9.70

Compliance & Legal

What Stripe Handles

• ✅ PCI compliance (credit card security)
• ✅ KYC (Know Your Customer) verification
• ✅ AML (Anti-Money Laundering) checks
• ✅ Tax reporting (1099-K for sellers earning >$600/year)
• ✅ Fraud prevention and detection
• ✅ Chargeback management

What You Handle

• Platform Terms of Service
• Privacy Policy
• Seller Agreement
• License agreements (Basic, Premium, Exclusive)

Going Live Checklist

1. [ ] Complete Stripe business verification
2. [ ] Test complete flow in test mode
3. [ ] Switch to live mode API keys
4. [ ] Create live mode webhook endpoint
5. [ ] Update webhook secret in Workers
6. [ ] Test with real payment (small amount)
7. [ ] Verify webhook delivery works
8. [ ] Confirm seller receives payout

Support Resources

• Stripe Connect Documentation
• Express Accounts Guide
• Connect Testing Guide
• Stripe Connect Support