# 🚀 Production Setup Guide

## Complete Stripe Integration Implementation

This guide covers the complete production setup for the Stripe Elements integration, including secure key storage, backend server, webhook handling, and comprehensive error handling.

## 📋 What's Been Implemented

### ✅ 1. Frontend Integration
- **Manual credit card form completely removed** from step_four.rs
- **Real Stripe Elements integration** with proper JavaScript interop
- **Automatic fallback to demo mode** when server is not available
- **Comprehensive error handling** and user guidance

### ✅ 2. Backend Server (`src/bin/server.rs`)
- **Payment intent creation endpoint**: `/company/create-payment-intent`
- **Webhook handling**: `/webhooks/stripe`
- **Payment success page**: `/company/payment-success`
- **Health check**: `/api/health`
- **Static file serving** for WASM, HTML, CSS, JS
- **CORS configuration** for development

### ✅ 3. Environment Configuration
- **Secure key storage** in `.env` file
- **Environment variable validation**
- **Development and production configurations**

### ✅ 4. Pricing Logic
- **Automatic pricing calculation** based on company type and payment plan
- **Discount handling** (20% yearly, 40% two-year)
- **ZDFZ Twin fee inclusion** ($2/month)

### ✅ 5. Error Handling
- **Comprehensive error responses**
- **Stripe API error handling**
- **Network failure fallbacks**
- **User-friendly error messages**

## 🔧 Setup Instructions

### Step 1: Get Stripe API Keys

1. **Create Stripe Account**: [https://stripe.com](https://stripe.com)
2. **Access Dashboard**: [https://dashboard.stripe.com](https://dashboard.stripe.com)
3. **Get API Keys**: Developers → API keys
   - Copy **Publishable key** (starts with `pk_test_`)
   - Copy **Secret key** (starts with `sk_test_`)

### Step 2: Configure Environment

1. **Copy environment template**:
   ```bash
   cp .env.example .env
   ```

2. **Edit `.env` file**:
   ```bash
   # Stripe Configuration
   STRIPE_PUBLISHABLE_KEY=pk_test_YOUR_ACTUAL_KEY_HERE
   STRIPE_SECRET_KEY=sk_test_YOUR_ACTUAL_SECRET_KEY_HERE
   STRIPE_WEBHOOK_SECRET=whsec_YOUR_WEBHOOK_SECRET_HERE
   
   # Server Configuration
   PORT=8080
   HOST=127.0.0.1
   RUST_LOG=info
   ```

3. **Update frontend key** in `index.html`:
   ```javascript
   const STRIPE_PUBLISHABLE_KEY = 'pk_test_YOUR_ACTUAL_KEY_HERE';
   ```

### Step 3: Run the Server

1. **Install dependencies**:
   ```bash
   cargo build --features server
   ```

2. **Start the server**:
   ```bash
   cargo run --bin server --features server
   ```

3. **Verify server is running**:
   ```bash
   curl http://127.0.0.1:8080/api/health
   ```

### Step 4: Set Up Webhooks (Production)

1. **In Stripe Dashboard**: Developers → Webhooks
2. **Add endpoint**: `https://yourdomain.com/webhooks/stripe`
3. **Select events**:
   - `payment_intent.succeeded`
   - `payment_intent.payment_failed`
4. **Copy webhook secret** to `.env` file

## 🧪 Testing

### Test with Demo Mode (No Server)
```javascript
window.testStripeIntegration()
```

### Test with Real Server
1. Start server: `cargo run --bin server --features server`
2. Navigate to entities page
3. Complete registration form
4. Use test cards:
   - **Success**: 4242 4242 4242 4242
   - **Declined**: 4000 0000 0000 0002
   - **3D Secure**: 4000 0025 0000 3155

## 📊 Pricing Structure

| Company Type | Setup Fee | Monthly Fee | Total Monthly |
|--------------|-----------|-------------|---------------|
| Single FZC | $20 | $20 + $2 | $22 |
| Startup FZC | $50 | $50 + $2 | $52 |
| Growth FZC | $1000 | $100 + $2 | $102 |
| Global FZC | $2000 | $200 + $2 | $202 |
| Cooperative FZC | $2000 | $200 + $2 | $202 |

**Payment Plans:**
- **Monthly**: Setup + Monthly fee
- **Yearly**: Setup + (Monthly × 12 × 0.8) - 20% discount
- **Two Year**: Setup + (Monthly × 24 × 0.6) - 40% discount

## 🔒 Security Best Practices

### Environment Variables
- ✅ **Never commit `.env` to version control**
- ✅ **Use different keys for development/production**
- ✅ **Rotate keys regularly**
- ✅ **Restrict API key permissions in Stripe Dashboard**

### Server Security
- ✅ **Webhook signature verification** (implemented)
- ✅ **CORS configuration** for allowed origins
- ✅ **Input validation** on all endpoints
- ✅ **Error message sanitization**

### Frontend Security
- ✅ **Publishable keys only** (safe for frontend)
- ✅ **No sensitive data in client code**
- ✅ **Secure payment form** via Stripe Elements

## 🔄 Webhook Events Handled

### `payment_intent.succeeded`
- Company registration completion
- Database updates
- Confirmation emails
- Account activation

### `payment_intent.payment_failed`
- Failed payment logging
- User notification
- Retry mechanisms

## 📁 File Structure

```
freezone/platform/
├── .env                          # Environment variables (DO NOT COMMIT)
├── .env.example                  # Environment template
├── Cargo.toml                    # Dependencies with server feature
├── index.html                    # Frontend with Stripe integration
├── src/
│   ├── bin/
│   │   └── server.rs            # Backend server with payment endpoints
│   ├── components/
│   │   └── entities/
│   │       └── company_registration/
│   │           └── step_four.rs # Updated payment step (no manual form)
│   └── models/
│       └── company.rs           # Data models
└── static/
    └── js/
        └── stripe-integration.js # Stripe JavaScript (if needed)
```

## 🚀 Deployment

### Development
```bash
# Start WASM dev server
trunk serve

# Start backend server (separate terminal)
cargo run --bin server --features server
```

### Production
```bash
# Build WASM
trunk build --release

# Build and run server
cargo build --release --features server
./target/release/server
```

## 🐛 Troubleshooting

### Common Issues

1. **"Invalid API Key"**
   - Check `.env` file has correct Stripe keys
   - Verify keys are for correct environment (test/live)

2. **"Payment form not loading"**
   - Check browser console for errors
   - Verify Stripe publishable key in `index.html`
   - Check network tab for failed requests

3. **"Server not available"**
   - Ensure server is running: `cargo run --bin server --features server`
   - Check server logs for errors
   - Verify port 8080 is available

4. **"CORS errors"**
   - Check server CORS configuration
   - Ensure frontend and backend on same origin for development

### Debug Commands

```bash
# Check server health
curl http://127.0.0.1:8080/api/health

# Test payment intent creation
curl -X POST http://127.0.0.1:8080/company/create-payment-intent \
  -H "Content-Type: application/json" \
  -d '{"company_name":"Test","company_type":"Single FZC","payment_plan":"monthly","final_agreement":true,"agreements":["terms"]}'

# Check server logs
RUST_LOG=debug cargo run --bin server --features server
```

## ✅ Success Criteria

When everything is working correctly:

1. ✅ **Manual credit card form is gone** from step 4
2. ✅ **Real Stripe Elements widget appears** when payment is ready
3. ✅ **Server creates payment intents** successfully
4. ✅ **Webhooks process payment events** correctly
5. ✅ **Test payments complete** end-to-end
6. ✅ **Error handling works** gracefully
7. ✅ **Demo mode works** when server is unavailable

The integration is now production-ready with secure key storage, comprehensive error handling, and real Stripe payment processing!