# Stripe Payments Implementation Plan

## Current State

The app has a basic payment infrastructure in place:

1. **Database**: `payments` table exists with fields:
   - `id`, `match_id`, `company_id`, `amount` (default 50.00)
   - `status`: 'pending' | 'charged' | 'refunded'
   - `stripe_payment_id`: nullable text field

2. **API**: Basic `/api/payments/create` endpoint that:
   - Creates a payment record in Supabase
   - Does NOT integrate with Stripe yet
   - Only records the intent to pay

3. **UI**: Contractor matches page has:
   - "Hire — $50 Fee" button
   - Creates payment record on hire
   - No actual payment collection

## What Needs to Be Built

### 1. Install Stripe Dependencies
```bash
npm install stripe @stripe/stripe-js
```

### 2. Environment Variables (add to .env.local)
```
# Stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
```

### 3. Backend: Stripe Setup

Create `src/lib/stripe/server.ts`:
- Initialize Stripe with secret key
- Helper functions for payment intents

### 4. Backend: Payment Intent API

Update `/api/payments/create`:
- Create Stripe PaymentIntent
- Store `payment_intent_id` in database
- Return client secret to frontend

New endpoint `/api/payments/confirm`:
- Confirm payment after Stripe success
- Update payment status to 'charged'
- Update match status to 'hired'

New endpoint `/api/webhooks/stripe`:
- Handle Stripe webhooks (payment success/failure)
- Update payment records
- Send notifications

### 5. Frontend: Stripe Integration

Create `src/components/payment/StripeProvider.tsx`:
- Stripe Elements wrapper

Create `src/components/payment/PaymentForm.tsx`:
- Credit card input using Stripe Elements
- Payment submission
- Error handling

### 6. Frontend: Payment Modal

Create `src/components/payment/HirePaymentModal.tsx`:
- Modal triggered on "Hire" button
- Shows $50 fee explanation
- Stripe payment form
- Success/error states

### 7. Flow: Hire with Payment

1. Contractor clicks "Hire — $50 Fee"
2. Modal opens with payment form
3. Create payment intent via API
4. Customer enters card details
5. Confirm payment with Stripe
6. Webhook updates payment status
7. Match marked as 'hired'
8. Worker gets notification

### 8. Additional Features

- **Saved Cards**: Allow contractors to save payment methods
- **Payment History**: Page to view past payments
- **Receipts**: Generate PDF receipts for completed payments
- **Refund Support**: Admin ability to refund payments

## Implementation Order

### Phase 1: Core Payment Flow (MVP)
1. Install Stripe packages
2. Create Stripe server utility
3. Update `/api/payments/create` to create PaymentIntent
4. Create payment modal with Stripe Elements
5. Update hire flow to collect payment first
6. Create webhook handler for payment confirmation

### Phase 2: Polish & Edge Cases
1. Error handling for failed payments
2. Loading states during payment
3. Success/failure notifications
4. Payment retry mechanism
5. Handle webhook failures gracefully

### Phase 3: Advanced Features (Post-Launch)
1. Saved payment methods
2. Payment history page
3. Receipt generation
4. Refund functionality
5. Stripe Connect for future marketplace features

## Security Considerations

- Never log full card details
- Use Stripe Elements (PCI compliance)
- Validate all webhooks with signature
- Rate limit payment endpoints
- Use idempotency keys for PaymentIntents
- Secure webhook endpoint (verify Stripe signature)

## Testing

Test cards from Stripe docs:
- Success: `4242 4242 4242 4242`
- Decline: `4000 0000 0000 0002`
- Insufficient funds: `4000 0000 0000 9995`

## Notes

- $50 is a one-time fee per hire (not per worker per job)
- Payment is triggered when contractor confirms hire
- Worker doesn't need Stripe account (contractor pays)
- For future: Could add Stripe Connect to let workers receive payments