amit/quantum-ai-v2
1
0
Fork 0
mirror of https://github.com/thecyberlearn/quantum-ai-v2.git synced 2026-08-18 19:52:59 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update documentation for current payment system

Browse Source 
📚 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>
This commit is contained in:
Claude 2025-07-12 19:17:24 +05:30
parent 58b92b98e4
commit 87daf4f7ab
3 changed files with 338 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
docs/CLAUDE.md
View File

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

266
docs/PAYMENT_SYSTEM.md Normal file
View File

@ -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.

26
docs/RAILWAY_SETUP.md
View File

@ -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_WEBHOOK_SECRET` - Your Stripe webhook secret
- `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` - Your Stripe publishable key
- `STRIPE_SECRET_KEY` - Your Stripe secret key (sk_test_...)
- `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` - Your Stripe publishable key (pk_test_...)
- `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_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
# Stripe (API-based payment system)
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
# 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.