blackcanyontickets/reactrebuild0825/STRIPE_CONNECT_README.md

Stripe Connect Integration

This implementation provides end-to-end Stripe Connect onboarding for organizations to link their own Stripe accounts.

Overview

• Each organization connects its own Stripe Express account
• Payment data stored in Firestore: orgs/{orgId}.payment
• No secrets stored client-side - all Stripe API calls via Cloud Functions
• Publish checklist validates payment connection before event goes live

Backend (Cloud Functions)

Environment Variables

Set these in Firebase Functions config:

# Stripe Configuration
firebase functions:config:set stripe.secret_key="sk_test_your_stripe_secret_key"
firebase functions:config:set stripe.webhook_secret="whsec_your_webhook_secret"

# Application Configuration  
firebase functions:config:set app.url="https://your-app-domain.com"

For local development, create functions/.runtimeconfig.json:

{
  "stripe": {
    "secret_key": "sk_test_your_stripe_secret_key",
    "webhook_secret": "whsec_your_webhook_secret"
  },
  "app": {
    "url": "http://localhost:5173"
  }
}

API Endpoints

The Cloud Functions provide these endpoints:

1. POST /stripeConnectStart

   • Input: { orgId: string, returnTo?: string }
   • Creates Stripe Express account if needed
   • Returns onboarding URL for Stripe Connect flow

2. GET /stripeConnectStatus?orgId=...

   • Fetches current account status from Stripe
   • Updates Firestore with latest connection state
   • Returns sanitized payment data

3. POST /stripeWebhook

   • Handles account.updated events from Stripe
   • Updates organization payment status in Firestore
   • Verifies webhook signatures for security

Deployment

# Install dependencies
cd functions && npm install

# Deploy all functions
firebase deploy --only functions

# Deploy specific functions
firebase deploy --only functions:stripeConnectStart,stripeConnectStatus,stripeWebhook

Frontend Integration

PaymentSettings Component

Located at /org/:orgId/payments, this component:

• Shows current Stripe Connect status
• Provides "Connect Stripe" button that redirects to Stripe onboarding
• Handles return flow with status updates
• Includes disconnect functionality (stub)

Publish Event Integration

The PublishEventModal includes payment validation:

• Checks org.payment.connected === true before allowing publish
• Provides "Connect Payments" button that navigates to payment settings
• Prevents event publishing until payment is configured

Usage Example

import { PaymentSettings } from './features/org/PaymentSettings';

// Navigate to payment settings
navigate(`/org/${orgId}/payments`);

// The component handles the full onboarding flow:
// 1. User clicks "Connect Stripe"
// 2. Redirects to Stripe Express onboarding  
// 3. Returns to payment settings with status
// 4. Status automatically refreshes and updates UI

Firestore Schema

Organization Document

// /orgs/{orgId}
{
  id: string;
  name: string;
  // ... other fields
  payment?: {
    provider: 'stripe';
    connected: boolean;
    stripe: {
      accountId: string;
      detailsSubmitted: boolean;  
      chargesEnabled: boolean;
      businessName: string;
    };
  };
}

Example States

// Not connected
payment: undefined

// Account created, setup incomplete  
payment: {
  provider: 'stripe',
  connected: false,
  stripe: {
    accountId: 'acct_1234567890',
    detailsSubmitted: false,
    chargesEnabled: false, 
    businessName: ''
  }
}

// Fully connected and ready
payment: {
  provider: 'stripe', 
  connected: true,
  stripe: {
    accountId: 'acct_1234567890',
    detailsSubmitted: true,
    chargesEnabled: true,
    businessName: 'Example Business Inc.'
  }
}

Webhook Configuration

1. Go to your Stripe Dashboard
2. Click "Add endpoint"
3. Set endpoint URL: https://us-central1-YOUR_PROJECT_ID.cloudfunctions.net/stripeWebhook
4. Select events: account.updated
5. Copy the webhook secret and update Functions config

Testing Flow

1. Start onboarding: Click "Connect Stripe" in payment settings
2. Complete Stripe setup: Fill out Stripe Express onboarding form
3. Return to app: Redirected back with status=connected parameter
4. Auto-refresh: Status automatically updates to show connection state
5. Publish validation: Event publish now passes payment check

Development

Local Testing

1. Start Firebase emulators:

firebase emulators:start --only functions,firestore

2. Update frontend API URL in PaymentSettings.tsx:

const API_BASE = 'http://localhost:5001/your-project-id/us-central1';

3. Test webhook with Stripe CLI:

stripe listen --forward-to localhost:5001/your-project-id/us-central1/stripeWebhook

Mock Data

The demo includes mock users with different payment states:

• Admin user: Fully connected Stripe account
• Organizer user: Incomplete setup (shows payment required)
• Staff user: No payment data (read-only access)

Security Features

• ✅ No client secrets: All Stripe API calls server-side only
• ✅ Webhook verification: Signatures validated on all webhooks
• ✅ CORS protection: Functions restricted to app domains
• ✅ Auth validation: Firestore rules enforce organization access
• ✅ Data sanitization: Only necessary fields returned to frontend

Next Steps

To extend this implementation:

1. Payment processing: Create checkout sessions with connected accounts
2. Application fees: Configure platform fees on transactions
3. Payout management: Monitor and manage payouts to connected accounts
4. Tax reporting: Implement 1099 reporting for connected accounts
5. Compliance: Add additional verification steps as needed

The foundation is now in place for full Stripe Connect payment processing!