Update documentation for current payment system

📚 DOCUMENTATION UPDATED:

1. CLAUDE.md Updates:
   - Updated project overview to reflect API-based payment verification
   - Added comprehensive Payment System Architecture section
   - Documented current Stripe integration approach
   - Added environment variables and URL routing info

2. New PAYMENT_SYSTEM.md:
   - Complete Stripe setup guide
   - API-based verification flow documentation
   - Testing and troubleshooting guides
   - Security considerations and best practices

3. RAILWAY_SETUP.md Updates:
   - Updated Stripe environment variables section
   - Added payment system notes
   - Clarified webhook secret as optional
   - Cross-referenced new payment documentation

Result: Comprehensive, up-to-date documentation for the production payment system.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-NetCop Hub is a Django-based AI agent marketplace that allows users to purchase and use various AI-powered agents for tasks like social media ad generation, data analysis, weather reporting, and more. The system features a wallet-based payment system with Stripe integration and N8N webhook processing.
+NetCop Hub is a Django-based AI agent marketplace that allows users to purchase and use various AI-powered agents for tasks like social media ad generation, data analysis, weather reporting, and more. The system features a wallet-based payment system with Stripe integration using API-based payment verification for reliable, instant transactions.
 
 ### Project Structure
 ```
@@ -458,6 +458,59 @@ function updateWalletBalance(newBalance) {
 
 This ensures users never lose money for failed processing while maintaining simple, efficient code.
 
+## Payment System Architecture
+
+### Stripe Integration (API-Based Verification)
+
+The payment system uses **API-based verification** instead of webhooks for reliable, instant payment processing:
+
+#### Payment Flow
+```
+1. User clicks "💳 Top Up Wallet"
+2. Create Stripe checkout session via API
+3. User completes payment on Stripe
+4. Stripe redirects to success page with session_id
+5. Success page verifies payment via Stripe API
+6. Wallet balance updated immediately
+7. Transaction recorded as "Wallet top-up via Stripe"
+```
+
+#### Key Components
+- **StripePaymentHandler** (`wallet/stripe_handler.py`): Handles session creation and verification
+- **Success Page Verification** (`core/views.py`): Automatic payment verification on return
+- **Clean Transaction Descriptions**: Professional "Wallet top-up via Stripe" messages
+- **No Webhook Dependency**: Reliable without webhook delivery issues
+
+#### Configuration
+```python
+# settings.py
+STRIPE_SECRET_KEY = 'sk_test_...'  # From .env
+STRIPE_PUBLISHABLE_KEY = 'pk_test_...'  # From .env
+STRIPE_WEBHOOK_SECRET = 'whsec_...'  # Optional (backup)
+```
+
+#### Environment Variables
+```bash
+# .env
+STRIPE_SECRET_KEY=sk_test_your_key_here
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_key_here
+STRIPE_WEBHOOK_SECRET=whsec_your_secret_here  # Optional
+```
+
+### Payment System URLs
+- `/wallet/` - Wallet overview and transactions
+- `/wallet/topup/` - Payment amount selection
+- `/wallet/top-up/success/` - Payment verification and confirmation
+- `/wallet/top-up/cancel/` - Payment cancellation
+- `/stripe/debug/` - Stripe connectivity debugging (dev only)
+
+### Advantages of API Verification
+- **Instant confirmation** - No waiting for webhook delivery
+- **Reliable** - No webhook delivery failures
+- **Immediate user feedback** - Balance updates immediately
+- **Simpler debugging** - You control the verification timing
+- **Production-proven** - Used by many successful platforms
+
 ## Current Architecture (Clean & Modern)
 
 The project uses a clean, modular individual agent architecture:

docs/PAYMENT_SYSTEM.md

@@ -0,0 +1,266 @@
+# Payment System Documentation
+
+## Overview
+
+NetCop Hub uses a Stripe-based payment system with API verification for reliable, instant wallet top-ups. The system bypasses webhook dependencies by verifying payments directly with the Stripe API when users return from successful payments.
+
+## Architecture
+
+### API-Based Verification (Current Implementation)
+
+Instead of relying on webhooks, the system uses direct API calls for payment verification:
+
+```
+User Payment Flow:
+1. User selects amount → Stripe checkout session created
+2. User pays on Stripe → Returns to success page with session_id
+3. Success page calls Stripe API → Verifies payment status
+4. If paid → Wallet balance updated immediately
+5. User sees instant confirmation
+```
+
+## Setup Guide
+
+### 1. Stripe Account Setup
+
+1. **Create Stripe Account**: https://dashboard.stripe.com/register
+2. **Get API Keys**:
+   - Go to Dashboard → Developers → API keys
+   - Copy **Publishable key** (starts with `pk_test_`)
+   - Copy **Secret key** (starts with `sk_test_`)
+
+### 2. Environment Configuration
+
+Add to your `.env` file:
+
+```bash
+# Stripe Configuration
+STRIPE_SECRET_KEY=sk_test_your_secret_key_here
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_publishable_key_here
+STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here  # Optional
+```
+
+### 3. Django Settings
+
+The settings are automatically configured in `settings.py`:
+
+```python
+# Stripe Configuration (automatically loaded from .env)
+STRIPE_SECRET_KEY = os.getenv('STRIPE_SECRET_KEY')
+STRIPE_PUBLISHABLE_KEY = os.getenv('NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY')
+STRIPE_WEBHOOK_SECRET = os.getenv('STRIPE_WEBHOOK_SECRET')
+```
+
+### 4. Railway Deployment
+
+Add environment variables in Railway dashboard:
+
+1. Go to your Railway project
+2. Navigate to Variables tab
+3. Add:
+   - `STRIPE_SECRET_KEY` = `sk_test_...`
+   - `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` = `pk_test_...`
+   - `STRIPE_WEBHOOK_SECRET` = `whsec_...` (optional)
+
+## Payment Flow Details
+
+### 1. Checkout Session Creation
+
+**File**: `wallet/stripe_handler.py`
+
+```python
+def create_checkout_session(self, user, amount, request=None):
+    # Creates Stripe checkout session
+    # Includes user metadata and success URL with session_id parameter
+    # Returns payment URL for redirect
+```
+
+**Features**:
+- Validates allowed amounts (10, 50, 100, 500 AED)
+- Includes comprehensive metadata
+- Auto-expires after 30 minutes
+- Immediate verification after creation
+
+### 2. Payment Verification
+
+**File**: `core/views.py` - `wallet_topup_success_view()`
+
+```python
+def wallet_topup_success_view(request):
+    session_id = request.GET.get('session_id')
+    # Verify payment with Stripe API
+    # Update wallet balance if successful
+    # Show confirmation message
+```
+
+**Process**:
+1. Extract `session_id` from URL parameters
+2. Call `stripe.checkout.Session.retrieve(session_id)`
+3. Check if `payment_status == 'paid'` and `status == 'complete'`
+4. Update user wallet balance
+5. Create transaction record
+6. Redirect to wallet with success message
+
+### 3. Error Handling
+
+- **Missing session_id**: Shows error, redirects to wallet
+- **Payment not completed**: Shows warning with instructions
+- **API errors**: Graceful error handling with user-friendly messages
+- **Duplicate processing**: Prevents double-charging with session ID checks
+
+## API Endpoints
+
+### Core Wallet URLs
+
+- `GET /wallet/` - Wallet dashboard and transaction history
+- `GET /wallet/topup/` - Payment amount selection page
+- `POST /wallet/topup/` - Create Stripe checkout session
+- `GET /wallet/top-up/success/?session_id=cs_...` - Payment verification
+- `GET /wallet/top-up/cancel/` - Payment cancellation handling
+
+### Debug Endpoints (Development)
+
+- `GET /stripe/debug/` - Test Stripe API connectivity and account info
+- `POST /stripe/webhook/` - Webhook endpoint (backup, not actively used)
+
+## Database Schema
+
+### WalletTransaction Model
+
+```python
+class WalletTransaction(models.Model):
+    user = models.ForeignKey(User, on_delete=models.CASCADE)
+    amount = models.DecimalField(max_digits=10, decimal_places=2)
+    type = models.CharField(max_length=20)  # 'top_up' or 'agent_usage'
+    description = models.CharField(max_length=255)
+    stripe_session_id = models.CharField(max_length=255, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+```
+
+### User Wallet Methods
+
+```python
+class User(AbstractUser):
+    wallet_balance = models.DecimalField(max_digits=10, decimal_places=2, default=0)
+    
+    def add_balance(self, amount, description, stripe_session_id=None):
+        # Adds money to wallet and creates transaction record
+    
+    def deduct_balance(self, amount, description, agent_slug):
+        # Removes money for agent usage
+```
+
+## Testing
+
+### Test Payment Flow
+
+1. **Local Testing**:
+   ```bash
+   python manage.py runserver
+   # Visit http://localhost:8000/wallet/topup/
+   # Use test card: 4242 4242 4242 4242
+   ```
+
+2. **Stripe Test Cards**:
+   - **Success**: `4242 4242 4242 4242`
+   - **Decline**: `4000 0000 0000 0002`
+   - **Requires authentication**: `4000 0025 0000 3155`
+
+3. **Debugging**:
+   - Visit `/stripe/debug/` to test API connectivity
+   - Check Railway logs for payment verification details
+   - Monitor Stripe dashboard for session creation
+
+### Test Scenarios
+
+- ✅ **Successful payment**: Amount added, transaction recorded
+- ✅ **Cancelled payment**: No charge, user returned to form
+- ✅ **Duplicate session**: Prevents double-charging
+- ✅ **Network errors**: Graceful error handling
+- ✅ **Invalid session**: Error message with support contact
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"No session found"**:
+   - Check if session_id parameter is in success URL
+   - Verify Stripe API keys are correct
+   - Check Railway environment variables
+
+2. **"Payment verification failed"**:
+   - Confirm payment was completed on Stripe
+   - Check Stripe dashboard for payment status
+   - Verify API version compatibility
+
+3. **"Session already processed"**:
+   - Normal behavior - prevents double-charging
+   - User balance was already updated
+
+### Debug Steps
+
+1. **Check Stripe Configuration**:
+   ```bash
+   # Visit debug endpoint
+   curl https://your-app.up.railway.app/stripe/debug/
+   ```
+
+2. **Verify Environment Variables**:
+   ```bash
+   # In Railway dashboard, check Variables tab
+   # Ensure all Stripe keys are set correctly
+   ```
+
+3. **Monitor Logs**:
+   ```bash
+   # Railway logs show detailed payment verification
+   # Look for "[STRIPE DEBUG]" messages
+   ```
+
+## Security Considerations
+
+### API Key Security
+- ✅ **Secret keys**: Stored in environment variables, never in code
+- ✅ **Publishable keys**: Safe to expose in frontend
+- ✅ **Test vs Live**: Always use test keys for development
+
+### Payment Security
+- ✅ **Amount validation**: Only allows predefined amounts (10, 50, 100, 500)
+- ✅ **User authentication**: All payment endpoints require login
+- ✅ **Session verification**: Direct API verification prevents tampering
+- ✅ **Duplicate prevention**: Session ID tracking prevents double-charging
+
+### Data Protection
+- ✅ **No sensitive data storage**: Credit card info handled by Stripe
+- ✅ **Transaction records**: Only store metadata and amounts
+- ✅ **User privacy**: Email and user ID properly associated
+
+## Advantages of This Approach
+
+### vs Webhooks
+- **Reliability**: No webhook delivery failures
+- **Speed**: Instant verification when user returns
+- **Debugging**: Easier to trace and debug payment flows
+- **User Experience**: Immediate feedback and balance updates
+
+### vs Frontend-Only
+- **Security**: Server-side verification prevents tampering
+- **Reliability**: Works even if frontend JavaScript fails
+- **Data Integrity**: Database updates happen server-side
+
+### Production Ready
+- **Scalability**: API calls scale better than webhook processing
+- **Monitoring**: Easier to monitor and alert on payment issues
+- **Maintenance**: Simpler codebase without webhook infrastructure
+
+## Migration from Webhook System
+
+If migrating from a webhook-based system:
+
+1. **Remove webhook endpoints** and processing code
+2. **Update success URLs** to include `{CHECKOUT_SESSION_ID}` parameter
+3. **Implement verification** in success page handler
+4. **Test thoroughly** with test payments
+5. **Monitor logs** during transition period
+
+The API-based approach is more reliable and provides better user experience than webhook-dependent systems.

docs/RAILWAY_SETUP.md

@@ -26,11 +26,11 @@ After adding PostgreSQL, check that these environment variables are set in Railw
 
 **API Keys:**
 - `OPENWEATHER_API_KEY` - Your OpenWeather API key
-- `STRIPE_SECRET_KEY` - Your Stripe secret key
+- `STRIPE_SECRET_KEY` - Your Stripe secret key (sk_test_...)
-- `STRIPE_WEBHOOK_SECRET` - Your Stripe webhook secret
+- `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` - Your Stripe publishable key (pk_test_...)
-- `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` - Your Stripe publishable key
+- `STRIPE_WEBHOOK_SECRET` - Your Stripe webhook secret (optional - whsec_...)
 
-**Webhook URLs:**
+**N8N Webhook URLs:**
 - `N8N_WEBHOOK_DATA_ANALYZER` - Your N8N webhook URL
 - `N8N_WEBHOOK_JOB_POSTING` - Your N8N webhook URL  
 - `N8N_WEBHOOK_SOCIAL_ADS` - Your N8N webhook URL
@@ -91,10 +91,10 @@ DATABASE_URL=postgresql://...
 # OpenWeather API
 OPENWEATHER_API_KEY=your-openweather-api-key
 
-# Stripe
+# Stripe (API-based payment system)
-STRIPE_SECRET_KEY=sk_test_...
+STRIPE_SECRET_KEY=sk_test_your_secret_key_here
-STRIPE_WEBHOOK_SECRET=whsec_...
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_publishable_key_here
-NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here  # Optional
 
 # N8N Webhooks
 N8N_WEBHOOK_DATA_ANALYZER=https://your-n8n.com/webhook/data-analyzer
@@ -139,5 +139,15 @@ Superusers: 1
 
 **Key:** Look for `postgresql` engine, not `sqlite3`!
 
+## Payment System Notes
+
+The payment system uses **API-based verification** instead of webhooks:
+- ✅ **More reliable** than webhook delivery
+- ✅ **Instant confirmation** when users return from Stripe
+- ✅ **No webhook delivery issues** on Railway
+- ✅ **Simpler debugging** and maintenance
+
+See `docs/PAYMENT_SYSTEM.md` for detailed payment system documentation.
+