255 lines
7.4 KiB
Markdown
255 lines
7.4 KiB
Markdown
# 🚀 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**: `/api/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/api/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! |