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:

```bash
# 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`:

```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

```bash
# 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

```tsx
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

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

### Example States

```javascript
// 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](https://dashboard.stripe.com/webhooks)
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:
```bash
firebase emulators:start --only functions,firestore
```

2. Update frontend API URL in `PaymentSettings.tsx`:
```typescript
const API_BASE = 'http://localhost:5001/your-project-id/us-central1';
```

3. Test webhook with Stripe CLI:
```bash
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!