freezone/platform/PRODUCTION_SETUP.md

🚀 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
2. Access Dashboard: 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:

   cp .env.example .env
   

2. Edit .env file:

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

   const STRIPE_PUBLISHABLE_KEY = 'pk_test_YOUR_ACTUAL_KEY_HERE';
   

Step 3: Run the Server

1. Install dependencies:

   cargo build --features server
   

2. Start the server:

   cargo run --bin server --features server
   

3. Verify server is running:

   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)

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

# Start WASM dev server
trunk serve

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

Production

# 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

# 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!