blackcanyontickets/reactrebuild0825/STRIPE_CONNECT_SETUP.md

Stripe Connect Setup Guide

This guide walks you through setting up Stripe Connect onboarding for organizations using Firebase Cloud Functions.

Architecture Overview

• Frontend: React components for Stripe Connect UI
• Backend: Firebase Cloud Functions handling Stripe API calls
• Database: Firestore with organization payment data
• Security: No secrets stored client-side, only in Functions environment

Prerequisites

1. Firebase project with Functions enabled
2. Stripe account with Connect enabled
3. Node.js 20+ for Cloud Functions

Quick Start

1. Install Dependencies

# Install Firebase CLI globally
npm install -g firebase-tools

# Install Functions dependencies
cd functions
npm install

2. Configure Firebase

# Login to Firebase
firebase login

# Initialize project (if not already done)
firebase init

# Select:
# - Functions: Configure and deploy Cloud Functions
# - Firestore: Deploy database rules
# - Hosting: Configure files for Firebase Hosting (optional)

3. Set Environment Variables

# Set Stripe secret key in Functions config
firebase functions:config:set stripe.secret_key="sk_test_your_stripe_secret_key"

# Set webhook secret
firebase functions:config:set stripe.webhook_secret="whsec_your_webhook_secret"

# Set app URL for redirect links
firebase functions:config:set app.url="https://your-app-domain.com"

# For local development, create functions/.runtimeconfig.json:
cd functions
echo '{
  "stripe": {
    "secret_key": "sk_test_your_stripe_secret_key",
    "webhook_secret": "whsec_your_webhook_secret"
  },
  "app": {
    "url": "http://localhost:5173"
  }
}' > .runtimeconfig.json

4. Deploy Functions

# Build and deploy all functions
firebase deploy --only functions

# Or deploy individual functions
firebase deploy --only functions:stripeConnectStart
firebase deploy --only functions:stripeConnectStatus
firebase deploy --only functions:stripeWebhook

5. Configure Stripe Webhooks

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 your Functions config

Frontend Integration

Using the Hook

import { useStripeConnect } from './hooks/useStripeConnect';

function PaymentSettings({ orgId }: { orgId: string }) {
  const { startOnboarding, checkStatus, isLoading, error, paymentData } = 
    useStripeConnect(orgId);

  const handleConnect = async () => {
    await startOnboarding('/settings?tab=payments');
  };

  return (
    <div>
      {paymentData?.connected ? (
        <p>✅ Stripe account connected!</p>
      ) : (
        <button onClick={handleConnect} disabled={isLoading}>
          {isLoading ? 'Connecting...' : 'Connect Stripe Account'}
        </button>
      )}
    </div>
  );
}

Using Components

import { StripeConnectStatus, PaymentSettings } from './components/billing';

function SettingsPage() {
  const orgId = 'your-org-id';

  return (
    <div>
      <h1>Settings</h1>
      <PaymentSettings />
      
      {/* Or use individual components */}
      <StripeConnectStatus 
        orgId={orgId}
        onStatusUpdate={(data) => console.log('Updated:', data)}
      />
    </div>
  );
}

Firestore Schema

The system stores payment data in the organization document:

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

API Endpoints

POST /api/stripe/connect/start

Starts Stripe Connect onboarding flow.

Request:

{
  "orgId": "org_12345",
  "returnTo": "/settings?tab=payments" // optional
}

Response:

{
  "url": "https://connect.stripe.com/setup/e/acct_..."
}

GET /api/stripe/connect/status

Gets current Stripe Connect status.

Query Params:

• orgId: Organization ID

Response:

{
  "payment": {
    "provider": "stripe",
    "connected": true,
    "stripe": {
      "accountId": "acct_12345",
      "detailsSubmitted": true,
      "chargesEnabled": true,
      "businessName": "Example Business"
    }
  }
}

POST /api/stripe/webhook

Handles Stripe platform webhooks.

Supported Events:

• account.updated: Updates organization payment status

Development

Local Testing

1. Start Firebase emulators:

firebase emulators:start --only functions,firestore

2. Update frontend API URL to use emulator:

// In useStripeConnect.ts
const getApiUrl = (): string => {
  if (import.meta.env.DEV) {
    return 'http://localhost:5001/YOUR_PROJECT_ID/us-central1';
  }
  return 'https://us-central1-YOUR_PROJECT_ID.cloudfunctions.net';
};

3. Test webhook locally using Stripe CLI:

stripe listen --forward-to localhost:5001/YOUR_PROJECT_ID/us-central1/stripeWebhook

Testing Flow

1. Start Onboarding: Call /api/stripe/connect/start
2. Complete Stripe Onboarding: Follow Stripe's onboarding flow
3. Return to App: User is redirected back with status
4. Check Status: Call /api/stripe/connect/status
5. Webhook Updates: Stripe sends account.updated webhooks

Security Considerations

• ✅ No secrets in frontend: All Stripe API calls happen server-side
• ✅ Webhook verification: All webhooks are verified with signatures
• ✅ CORS protection: Functions have restricted CORS policies
• ✅ Firestore rules: Database access controlled by authentication
• ✅ Environment isolation: Dev/staging/prod environment separation

Troubleshooting

Common Issues

1. CORS errors: Check that your domain is in the CORS configuration
2. Webhook failures: Verify webhook secret matches Stripe dashboard
3. Permission errors: Ensure Firestore rules allow organization access
4. Environment variables: Check Functions config with firebase functions:config:get

Debugging

# View function logs
firebase functions:log

# Check Functions config
firebase functions:config:get

# Test Functions locally
cd functions
npm run serve

Error Codes

• 400: Missing or invalid request parameters
• 404: Organization or Stripe account not found
• 405: HTTP method not allowed
• 500: Internal server error (check logs)

Production Checklist

• Stripe secret keys configured in Functions
• Webhook endpoint configured in Stripe Dashboard
• Firestore security rules deployed
• Frontend API URLs point to production Functions
• CORS policies configured for production domain
• Error monitoring enabled (Sentry/Cloud Logging)
• Rate limiting configured if needed

Next Steps

After setup, you can extend the system with:

1. Payment Processing: Create payment intents with connected accounts
2. Payouts: Configure automatic payouts to connected accounts
3. Fees: Implement application fees on transactions
4. Dashboard: Show earnings and transaction history
5. Compliance: Add tax reporting and regulatory features