feat: add advanced analytics and territory management system
- Add comprehensive analytics components with export functionality - Implement territory management with manager performance tracking - Add seatmap components for venue layout management - Create customer management features with modal interface - Add advanced hooks for dashboard flags and territory data - Implement seat selection and venue management utilities - Add type definitions for ticketing and seatmap systems 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
219
reactrebuild0825/STRIPE_CONNECT_README.md
Normal file
219
reactrebuild0825/STRIPE_CONNECT_README.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user