+ You have {pendingCreditPayments.length} credit purchase(s) pending approval +
+Bank: Standard Chartered Bank Pakistan
+Account Title: IGNY8 Technologies
+Account #: 01-2345678-01
+``` + +**Problem:** Bank details hardcoded in frontend. Should come from `PaymentMethodConfig` in backend. + +**Fix Required:** Fetch bank details from `/v1/billing/payment-configs/payment-methods/?country_code=PK&payment_method=bank_transfer` and display dynamically. + +--- + +### Account Lifecycle State Machine (Missing) + +The page doesn't follow a clear state machine. Here's what it SHOULD be: + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ ACCOUNT STATES │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────┐ Payment ┌──────────┐ Payment ┌──────────┐ │ +│ │ trial │ ────────────▶ │ pending_ │ ────────────▶ │ active │ │ +│ │ │ Required │ payment │ Success │ │ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +│ │ │ │ │ +│ │ │ Payment │ │ +│ │ │ Failed │ │ +│ ▼ ▼ ▼ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ expired │ │suspended │ ◀─────────── │ past_due │ │ +│ │ │ │ │ Auto │ │ │ +│ └──────────┘ └──────────┘ Suspend └──────────┘ │ +│ │ │ │ +│ │ Admin │ │ +│ │ Action │ │ +│ ▼ │ │ +│ ┌──────────┐ │ │ +│ │cancelled │ ◀──────────────────┘ │ +│ │ │ User Cancel │ +│ └──────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +**Each State Should Show:** + +| State | Plan Badge | Actions Available | Warnings | +|-------|------------|-------------------|----------| +| `trial` | "Trial (X days)" | Upgrade, Buy Credits | "Trial ends [date]" | +| `pending_payment` | "Awaiting Payment" | Pay Invoice, Change Method | "Complete payment to activate" | +| `active` | "Active" | Upgrade, Buy Credits, Cancel, Manage | None | +| `past_due` | "Payment Overdue" | Update Payment, Pay Now | "Update payment to avoid suspension" | +| `suspended` | "Suspended" | Pay to Reactivate | "Account suspended - pay to restore" | +| `cancelled` | "Cancels [date]" | Resubscribe | "Access ends [date]" | + +--- + +### Payment Options By State (Missing Restrictions) + +**Current:** All payment options shown regardless of account state. + +**Required Restrictions:** + +| Account State | Can Upgrade? | Can Buy Credits? | Can Change Plan? | Can Cancel? | +|---------------|--------------|------------------|------------------|-------------| +| `trial` | Yes | Yes | N/A | No | +| `pending_payment` | No (Pay first) | No (Pay first) | No | No | +| `active` | Yes | Yes | Yes | Yes | +| `past_due` | No (Pay first) | No | No | Yes | +| `suspended` | No | No | No | No | +| `cancelled` | Yes (Resubscribe) | No | No | No | + +--- + +### Summary of PlansAndBillingPage Fixes Needed + +| # | Issue | Severity | Effort | +|---|-------|----------|--------| +| 1 | Plan shows "Active" with unpaid invoice | CRITICAL | 30 min | +| 2 | Subscription states not reflected | CRITICAL | 1 hr | +| 3 | Upgrade available when payment pending | HIGH | 15 min | +| 4 | Cancel available for unpaid subscriptions | HIGH | 15 min | +| 5 | Manage Billing shown to non-Stripe users | HIGH | 15 min | +| 6 | No pending credit purchase indicator | HIGH | 30 min | +| 7 | Invoice status colors inconsistent | MEDIUM | 15 min | +| 8 | No payment method shown per invoice | MEDIUM | 30 min | +| 9 | Renewal date context wrong | MEDIUM | 15 min | +| 10 | Gateway selection not synced | MEDIUM | 30 min | +| 11 | Annual billing does nothing | LOW | 2 hrs | +| 12 | Bank details hardcoded | LOW | 1 hr | + +--- + +## Critical Issues (Immediate Action Required) + +### 1. PayPal Webhook Signature Not Enforced + +**Location:** `paypal_views.py:498-511` + +**Problem:** +```python +if not is_valid: + logger.warning("PayPal webhook signature verification failed") + # Optionally reject invalid signatures + # return Response({'error': 'Invalid signature'}, status=400) # COMMENTED OUT! +``` + +**Risk:** Malicious actors can craft fake webhook events to: +- Approve payments that never happened +- Cancel legitimate subscriptions +- Add credits without payment + +**Fix Required:** +```python +if not is_valid: + logger.error("PayPal webhook signature verification failed") + return Response({'error': 'Invalid signature'}, status=400) # UNCOMMENT +``` + +--- + +### 2. Stripe Webhook Not Idempotent (Double-Charge Risk) + +**Location:** `stripe_views.py:380-391` (_handle_checkout_completed) + +**Problem:** Webhook can be called multiple times for same event. No check prevents duplicate invoice/payment creation. + +**Scenario:** +1. Stripe sends webhook +2. Invoice and payment created +3. Stripe retries webhook (network timeout) +4. **Duplicate invoice and payment created** + +**Fix Required:** +```python +# At start of _handle_checkout_completed: +session_id = session.get('id') +if Payment.objects.filter(stripe_checkout_session_id=session_id).exists(): + logger.info(f"Webhook already processed for session {session_id}") + return # Already processed +``` + +--- + +### 3. PayPal Capture Order Not Idempotent + +**Location:** `paypal_views.py:261-365` (PayPalCaptureOrderView) + +**Problem:** If frontend calls `/capture-order/` twice (network timeout), payment captured twice. + +**Fix Required:** +```python +# Check if order already captured +existing = Payment.objects.filter(paypal_order_id=order_id, status='succeeded').first() +if existing: + return Response({'status': 'already_captured', 'payment_id': existing.id}) +``` + +--- + +### 4. Refund Functions Call Non-Existent Modules + +**Location:** `refund_views.py:160-208` + +**Problem:** +```python +from igny8_core.business.billing.utils.payment_gateways import get_stripe_client # DOESN'T EXIST +from igny8_core.business.billing.utils.payment_gateways import get_paypal_client # DOESN'T EXIST +``` + +**Risk:** Refunds marked as processed but **never actually charged back** to customer. + +**Fix Required:** Create the missing modules or use existing service classes: +```python +from igny8_core.business.billing.services.stripe_service import StripeService +from igny8_core.business.billing.services.paypal_service import PayPalService +``` + +--- + +### 5. Amount Validation Missing for PayPal + +**Location:** `paypal_views.py:569` + +**Problem:** +```python +amount = float(capture_result.get('amount', package.price)) # Trusts PayPal amount +``` + +**Risk:** If PayPal returns wrong amount, system processes it as correct. + +**Fix Required:** +```python +captured_amount = float(capture_result.get('amount', 0)) +expected_amount = float(package.price) +if abs(captured_amount - expected_amount) > 0.01: # Allow 1 cent tolerance + logger.error(f"Amount mismatch: captured={captured_amount}, expected={expected_amount}") + return Response({'error': 'Amount mismatch'}, status=400) +``` + +--- + +## High Priority Issues + +### 6. No Admin Dashboard for Pending Payments + +**Problem:** Admins must use Django admin to approve manual payments. + +**Missing Endpoint:** +``` +GET /v1/admin/billing/pending-payments/ - List pending approvals +POST /v1/admin/billing/payments/{id}/approve/ - Approve payment +POST /v1/admin/billing/payments/{id}/reject/ - Reject payment +``` + +**Required Implementation:** +```python +class AdminPaymentViewSet(viewsets.ModelViewSet): + permission_classes = [IsAdminUser] + + @action(detail=False, methods=['get']) + def pending(self, request): + payments = Payment.objects.filter(status='pending_approval') + return Response(PaymentSerializer(payments, many=True).data) + + @action(detail=True, methods=['post']) + def approve(self, request, pk=None): + payment = self.get_object() + PaymentService.approve_manual_payment(payment, request.user.id, request.data.get('notes')) + return Response({'status': 'approved'}) +``` + +--- + +### 7. Invoice Number Race Condition + +**Location:** `invoice_service.py:52-78` + +**Problem:** +```python +count = Invoice.objects.select_for_update().filter(...).count() +invoice_number = f"{prefix}-{count + 1:04d}" +while Invoice.objects.filter(invoice_number=invoice_number).exists(): # NOT LOCKED! + count += 1 +``` + +**Fix Required:** +```python +# Use database unique constraint + retry logic +@transaction.atomic +def generate_invoice_number(account_id, invoice_type='SUB'): + prefix = f"INV-{account_id}-{invoice_type}-{timezone.now().strftime('%Y%m')}" + for attempt in range(5): + count = Invoice.objects.filter(invoice_number__startswith=prefix).count() + invoice_number = f"{prefix}-{count + 1:04d}" + try: + # Use get_or_create with unique constraint + return invoice_number + except IntegrityError: + continue + raise ValueError("Unable to generate unique invoice number") +``` + +--- + +### 8. Browser Redirect Lost After Payment + +**Problem:** If user closes browser after Stripe payment but before redirect: +- Payment succeeds (webhook processes it) +- User doesn't know payment succeeded +- May attempt to pay again + +**Fix Required:** Add payment status check endpoint: +```python +# New endpoint +GET /v1/billing/payment-status/{session_id}/ + +# Frontend should check this on /account/plans load +const checkPaymentStatus = async (sessionId) => { + const response = await fetch(`/v1/billing/payment-status/${sessionId}/`); + if (response.data.status === 'completed') { + toast.success('Your previous payment was successful!'); + refreshUser(); + } +}; +``` + +--- + +### 9. Subscription Renewal Gets Stuck + +**Location:** `subscription_renewal.py:78-131` + +**Problem:** Status set to `pending_renewal` with no expiry or retry mechanism. + +**Fix Required:** +```python +# Add Celery task +@app.task +def check_stuck_renewals(): + """Run daily to check for stuck renewals""" + stuck = Subscription.objects.filter( + status='pending_renewal', + metadata__renewal_required_at__lt=timezone.now() - timedelta(days=7) + ) + for sub in stuck: + # Send reminder email + send_renewal_reminder(sub) + # After 14 days, suspend + if sub.metadata.get('renewal_required_at') < timezone.now() - timedelta(days=14): + sub.status = 'past_due' + sub.account.status = 'suspended' + sub.save() +``` + +--- + +### 10. Currency Exchange Rates Hardcoded + +**Location:** `currency.py:137-157` + +**Problem:** +```python +CURRENCY_MULTIPLIERS = { + 'PKR': 278.0, # STATIC - real rate changes daily! + 'INR': 83.0, + # ... +} +``` + +**Risk:** Users charged incorrect amounts over time. + +**Fix Required:** +```python +class ExchangeRateService: + CACHE_KEY = 'exchange_rates' + CACHE_TTL = 86400 # 24 hours + + @classmethod + def get_rate(cls, currency): + rates = cache.get(cls.CACHE_KEY) + if not rates: + rates = cls._fetch_from_api() + cache.set(cls.CACHE_KEY, rates, cls.CACHE_TTL) + return rates.get(currency, 1.0) + + @classmethod + def _fetch_from_api(cls): + # Use OpenExchangeRates, Fixer.io, or similar + response = requests.get('https://api.exchangerate-api.com/v4/latest/USD') + return response.json()['rates'] +``` + +--- + +## Medium Priority Issues + +### 11. No Promo Code/Discount Support + +**Missing Models:** +```python +class PromoCode(models.Model): + code = models.CharField(max_length=50, unique=True) + discount_type = models.CharField(choices=[('percent', '%'), ('fixed', '$')]) + discount_value = models.DecimalField(max_digits=10, decimal_places=2) + valid_from = models.DateTimeField() + valid_until = models.DateTimeField(null=True) + max_uses = models.IntegerField(null=True) + current_uses = models.IntegerField(default=0) + applicable_plans = models.ManyToManyField('Plan', blank=True) +``` + +--- + +### 12. No Partial Payment Support + +**Current:** User must pay full invoice amount. + +**Needed:** +- Split invoice into multiple payments +- Track partial payment progress +- Handle remaining balance + +--- + +### 13. No Dunning Management + +**Missing:** When payment fails: +- Day 1: Payment failed notification +- Day 3: Retry attempt + reminder +- Day 7: Second retry + warning +- Day 14: Account suspension warning +- Day 21: Account suspended + +--- + +### 14. No Manual Payment Reference Uniqueness + +**Location:** `models.py:487-490` + +**Fix:** +```python +manual_reference = models.CharField( + max_length=255, + blank=True, + unique=True, # ADD THIS + null=True # Allow null for non-manual payments +) +``` + +--- + +### 15. Refund Credit Deduction Race Condition + +**Location:** `refund_views.py:108-129` + +**Fix:** Use `select_for_update()`: +```python +with transaction.atomic(): + account = Account.objects.select_for_update().get(id=payment.account_id) + if account.credit_balance >= credits_to_deduct: + account.credit_balance -= credits_to_deduct + account.save() +``` + +--- + +### 16. Invoice Total Calculation Silent Failure + +**Location:** `models.py:439-448` + +**Problem:** +```python +except Exception: + pass # SILENT FAILURE! +``` + +**Fix:** +```python +except Exception as e: + logger.error(f"Invalid line item in invoice {self.id}: {item}, error: {e}") + raise ValueError(f"Invalid invoice line item: {item}") +``` + +--- + +### 17. No Webhook Event Storage + +**Missing:** All incoming webhooks should be stored for: +- Audit trail +- Replay on failure +- Debugging + +**Add Model:** +```python +class WebhookEvent(models.Model): + event_id = models.CharField(max_length=255, unique=True) + provider = models.CharField(max_length=20) # stripe, paypal + event_type = models.CharField(max_length=100) + payload = models.JSONField() + processed = models.BooleanField(default=False) + processed_at = models.DateTimeField(null=True) + error_message = models.TextField(blank=True) + created_at = models.DateTimeField(auto_now_add=True) +``` + +--- + +### 18. No Payment Audit Trail for Rejections + +**Missing Fields in Payment model:** +```python +rejected_by = models.ForeignKey('User', null=True, related_name='rejected_payments') +rejected_at = models.DateTimeField(null=True) +rejection_reason = models.TextField(blank=True) +``` + +--- + +## Recommendations Summary + +### Immediate (This Week) + +| # | Issue | Effort | Impact | +|---|-------|--------|--------| +| 1 | Enable PayPal webhook signature verification | 5 min | CRITICAL | +| 2 | Add Stripe webhook idempotency check | 30 min | CRITICAL | +| 3 | Add PayPal capture idempotency check | 30 min | CRITICAL | +| 4 | Fix refund module imports | 1 hr | CRITICAL | +| 5 | Add PayPal amount validation | 30 min | CRITICAL | + +### Short-Term (This Month) + +| # | Issue | Effort | Impact | +|---|-------|--------|--------| +| 6 | Build admin pending payments dashboard | 1 day | HIGH | +| 7 | Fix invoice number race condition | 2 hrs | HIGH | +| 8 | Add payment status check endpoint | 2 hrs | HIGH | +| 9 | Fix stuck renewal subscriptions | 1 day | HIGH | +| 10 | Implement dynamic currency rates | 1 day | HIGH | + +### Medium-Term (This Quarter) + +| # | Issue | Effort | Impact | +|---|-------|--------|--------| +| 11 | Promo code system | 3 days | MEDIUM | +| 12 | Partial payment support | 2 days | MEDIUM | +| 13 | Dunning management | 2 days | MEDIUM | +| 14 | Webhook event storage | 1 day | MEDIUM | +| 15 | Payment audit trail | 1 day | MEDIUM | + +--- + +## Architecture Assessment + +### What's Good + +1. **Clean separation** between frontend entry points, services, and backend +2. **Country-based logic** correctly isolates Pakistan users from PayPal +3. **Multi-gateway support** (Stripe, PayPal, Manual) well architected +4. **Service layer abstraction** (`StripeService`, `PayPalService`, `PaymentService`) +5. **Invoice and payment tracking** comprehensive +6. **Webhook handlers** exist for both gateways + +### What Needs Improvement + +1. **Idempotency** - Critical for payment processing +2. **Transaction safety** - Need more `@transaction.atomic()` and `select_for_update()` +3. **Observability** - No webhook event storage, limited metrics +4. **Admin tooling** - Manual payments need proper dashboard +5. **Error handling** - Too many silent failures +6. **Feature gaps** - No promo codes, partial payments, dunning + +--- + +## Final Assessment + +| Area | Rating | Notes | +|------|--------|-------| +| Documentation Accuracy | A | Matches codebase | +| Security | C | Webhook verification gaps | +| Reliability | C | Idempotency issues | +| Completeness | B | Core features present | +| Admin Experience | D | No proper dashboard | +| User Experience | B | Good flows, missing status checks | +| Code Quality | B | Good structure, some silent failures | + +**Overall Grade: C+** + +The payment system is functional but has critical security and reliability gaps that must be addressed before scaling. The architecture is sound, but implementation details need hardening. + +--- + +## Quick Wins (Can Do Today) + +1. Uncomment PayPal webhook signature rejection (5 min) +2. Add `@transaction.atomic()` to all payment handlers (30 min) +3. Add duplicate check before creating payments (30 min) +4. Add unique constraint to `manual_reference` (migration) +5. Remove silent `except: pass` blocks (30 min) + +--- + +*Report generated by deep audit of IGNY8 payment system codebase.* diff --git a/docs/90-REFERENCE/PAYMENT-SYSTEM-REFACTOR-PLAN.md b/docs/90-REFERENCE/PAYMENT-SYSTEM-REFACTOR-PLAN.md new file mode 100644 index 00000000..1e5298b2 --- /dev/null +++ b/docs/90-REFERENCE/PAYMENT-SYSTEM-REFACTOR-PLAN.md @@ -0,0 +1,1350 @@ +# Payment System Complete Refactor Plan + +> **Version:** 1.0 +> **Date:** January 7, 2026 +> **Status:** In Progress - Phase 1 Complete ✅ + +--- + +## Executive Summary + +This plan consolidates all audit findings and architectural discussions into a comprehensive refactor that will: + +1. **Simplify signup flow** - Remove payment gateway redirect from signup +2. **Unify payment experience** - Single payment interface in `/account/plans` +3. **Fix all critical security issues** - Webhook verification, idempotency +4. **Clean up dead code** - Remove `/pk` variant, country detection API, unused fields +5. **Implement proper state handling** - Account lifecycle properly reflected in UI + +--- + +## Architecture Changes + +### Before (Current) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ CURRENT FLOW │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ /signup OR /signup/pk │ +│ │ │ +│ ├── Country detection API call │ +│ ├── Load payment methods API call │ +│ ├── Show payment method selection │ +│ │ │ +│ └── On Submit: │ +│ ├── Stripe → Redirect to Stripe → Return to /plans │ +│ ├── PayPal → Redirect to PayPal → Return to /plans │ +│ └── Bank → Navigate to /plans (show banner) │ +│ │ +│ PROBLEMS: │ +│ - Two signup routes (/signup and /signup/pk) │ +│ - Country detection API complexity │ +│ - Payment gateway redirect from signup │ +│ - User loses context if redirect fails │ +│ - Duplicate payment logic (signup + plans page) │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### After (New) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ NEW FLOW │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ /signup (SINGLE ROUTE) │ +│ │ │ +│ ├── Country dropdown (auto-detect default using IP API) │ +│ ├── Plan selection │ +│ ├── NO payment method selection │ +│ │ │ +│ └── On Submit: │ +│ └── Create account (pending_payment) │ +│ └── Navigate to /account/plans │ +│ │ +│ /account/plans │ +│ │ │ +│ ├── IF new user (never paid): │ +│ │ └── Show PendingPaymentView (full page) │ +│ │ - Invoice details │ +│ │ - Payment method selection (based on country) │ +│ │ - Inline payment form │ +│ │ │ +│ ├── IF existing user (has paid before): │ +│ │ └── Show ActiveSubscriptionView │ +│ │ - Current plan details │ +│ │ - Credit balance │ +│ │ - Buy credits (modal) │ +│ │ - Billing history │ +│ │ - IF pending invoice: Show banner + Pay modal │ +│ │ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Phase 1: Backend Cleanup & Security Fixes ✅ + +### 1.1 Fix Critical Security Issues ✅ + +#### 1.1.1 Enable PayPal Webhook Signature Verification ✅ + +**File:** `backend/igny8_core/business/billing/views/paypal_views.py` + +```python +# Line ~510 - UNCOMMENT the rejection +if not is_valid: + logger.error("PayPal webhook signature verification failed") + return Response({'error': 'Invalid signature'}, status=400) # UNCOMMENT THIS +``` + +#### 1.1.2 Add Stripe Webhook Idempotency ✅ + +**File:** `backend/igny8_core/business/billing/views/stripe_views.py` + +```python +# Add at start of _handle_checkout_completed (around line 380): +@transaction.atomic +def _handle_checkout_completed(session): + session_id = session.get('id') + + # IDEMPOTENCY CHECK + if Payment.objects.filter( + metadata__stripe_checkout_session_id=session_id + ).exists(): + logger.info(f"Webhook already processed for session {session_id}") + return + + # ... rest of handler +``` + +#### 1.1.3 Add PayPal Capture Idempotency ✅ + +**File:** `backend/igny8_core/business/billing/views/paypal_views.py` + +```python +# Add at start of PayPalCaptureOrderView.post (around line 270): +def post(self, request): + order_id = request.data.get('order_id') + + # IDEMPOTENCY CHECK + existing = Payment.objects.filter( + paypal_order_id=order_id, + status='succeeded' + ).first() + if existing: + return Response({ + 'status': 'already_captured', + 'payment_id': existing.id, + 'message': 'This order has already been captured' + }) + + # ... rest of handler +``` + +#### 1.1.4 Add PayPal Amount Validation ✅ + +**File:** `backend/igny8_core/business/billing/views/paypal_views.py` + +```python +# In _process_credit_purchase (around line 570): +captured_amount = Decimal(str(capture_result.get('amount', '0'))) +expected_amount = Decimal(str(package.price)) + +if abs(captured_amount - expected_amount) > Decimal('0.01'): + logger.error(f"Amount mismatch: captured={captured_amount}, expected={expected_amount}") + return Response({ + 'error': 'Payment amount does not match expected amount', + 'captured': str(captured_amount), + 'expected': str(expected_amount) + }, status=400) +``` + +#### 1.1.5 Fix Refund Module Imports ✅ + +**File:** `backend/igny8_core/business/billing/views/refund_views.py` + +```python +# Replace non-existent imports (around line 160): +# FROM: +from igny8_core.business.billing.utils.payment_gateways import get_stripe_client +from igny8_core.business.billing.utils.payment_gateways import get_paypal_client + +# TO: +from igny8_core.business.billing.services.stripe_service import StripeService +from igny8_core.business.billing.services.paypal_service import PayPalService + +# Then use: +stripe_service = StripeService() +stripe_service.create_refund(payment_intent_id, amount) +``` + +--- + +### 1.2 Simplify Registration Serializer ✅ + +**File:** `backend/igny8_core/auth/serializers.py` + +**REMOVE from RegisterSerializer.create():** +- Stripe checkout session creation +- PayPal order creation +- `checkout_url` return +- `checkout_session_id` return +- `paypal_order_id` return + +**KEEP:** +- User creation +- Account creation with `status='pending_payment'` +- Subscription creation with `status='pending_payment'` +- Invoice creation +- AccountPaymentMethod creation (just store type, don't verify) + +**NEW create() method (simplified):** + +```python +def create(self, validated_data): + # Extract fields + plan_slug = validated_data.pop('plan_slug', 'free') + billing_country = validated_data.pop('billing_country', '') + + # Create user + user = User.objects.create_user(...) + + # Get plan + plan = Plan.objects.get(slug=plan_slug, is_active=True) + is_paid_plan = plan.price > 0 + + # Create account + account = Account.objects.create( + name=validated_data.get('account_name', user.username), + owner=user, + plan=plan, + credits=0 if is_paid_plan else plan.included_credits, + status='pending_payment' if is_paid_plan else 'active', + billing_country=billing_country, + ) + + if is_paid_plan: + # Create subscription + subscription = Subscription.objects.create( + account=account, + plan=plan, + status='pending_payment', + current_period_start=timezone.now(), + current_period_end=timezone.now() + timedelta(days=30), + ) + + # Create invoice + InvoiceService.create_subscription_invoice( + subscription=subscription, + payment_method=None, # Will be set when user pays + ) + + return user # NO checkout_url returned +``` + +**File:** `backend/igny8_core/auth/views.py` + +**REMOVE from RegisterView.post():** +- Stripe checkout session creation +- PayPal order creation +- `checkout_url` in response + +**NEW response (simplified):** + +```python +def post(self, request): + serializer = RegisterSerializer(data=request.data) + serializer.is_valid(raise_exception=True) + user = serializer.save() + + # Generate tokens + tokens = get_tokens_for_user(user) + + return Response({ + 'success': True, + 'user': UserSerializer(user).data, + 'tokens': tokens, + # NO checkout_url - user will pay on /account/plans + }) +``` + +--- + +### 1.3 Add Country List Endpoint ✅ + +**File:** `backend/igny8_core/auth/urls.py` (NEW) + +```python +class CountryListView(APIView): + """Returns list of countries for signup dropdown""" + permission_classes = [] # Public endpoint + + def get(self, request): + countries = [ + {'code': 'US', 'name': 'United States'}, + {'code': 'GB', 'name': 'United Kingdom'}, + {'code': 'CA', 'name': 'Canada'}, + {'code': 'AU', 'name': 'Australia'}, + {'code': 'PK', 'name': 'Pakistan'}, + {'code': 'IN', 'name': 'India'}, + # ... full list + ] + return Response({'countries': countries}) +``` + +**File:** `backend/igny8_core/auth/urls.py` + +```python +path('countries/', CountryListView.as_view(), name='country-list'), +``` + +--- + +### 1.4 Add WebhookEvent Model for Audit Trail ✅ + +**File:** `backend/igny8_core/business/billing/models.py` (ADD) + +```python +class WebhookEvent(models.Model): + """Store all incoming webhook events for audit and replay""" + event_id = models.CharField(max_length=255, unique=True) + provider = models.CharField(max_length=20) # 'stripe' or 'paypal' + event_type = models.CharField(max_length=100) + payload = models.JSONField() + processed = models.BooleanField(default=False) + processed_at = models.DateTimeField(null=True, blank=True) + error_message = models.TextField(blank=True) + created_at = models.DateTimeField(auto_now_add=True) + + class Meta: + indexes = [ + models.Index(fields=['provider', 'event_type']), + models.Index(fields=['processed']), + ] +``` + +--- + +### 1.5 Add Invoice Unique Constraint ✅ + +**Migration:** Add unique constraint to invoice_number + +```python +# In Invoice model +invoice_number = models.CharField(max_length=50, unique=True) # Already has unique=True +``` + +**Update invoice_service.py** to handle IntegrityError: + +```python +from django.db import IntegrityError + +@transaction.atomic +def generate_invoice_number(account_id, invoice_type='SUB'): + prefix = f"INV-{account_id}-{invoice_type}-{timezone.now().strftime('%Y%m')}" + + for attempt in range(5): + count = Invoice.objects.filter( + invoice_number__startswith=prefix + ).count() + invoice_number = f"{prefix}-{count + 1:04d}" + + # Check if exists (within transaction) + if not Invoice.objects.filter(invoice_number=invoice_number).exists(): + return invoice_number + + raise ValueError(f"Unable to generate unique invoice number after 5 attempts") +``` + +--- + +### 1.6 Add Manual Reference Uniqueness ✅ + +**Migration:** + +```python +class Migration(migrations.Migration): + operations = [ + migrations.AlterField( + model_name='payment', + name='manual_reference', + field=models.CharField( + max_length=255, + blank=True, + null=True, + unique=True, # ADD UNIQUE + ), + ), + ] +``` + +--- + +## Phase 2: Frontend Cleanup ✅ + +### 2.1 Simplify SignUpFormUnified.tsx ✅ + +**File:** `frontend/src/components/auth/SignUpFormUnified.tsx` + +**REMOVE:** ✅ +- Payment method selection UI +- Payment method loading from API (`/v1/billing/payment-configs/payment-methods/`) +- Stripe checkout redirect logic +- PayPal redirect logic +- `isPakistanSignup` variant logic +- All payment gateway-related state + +**KEEP:** ✅ +- Email, password, name fields +- Plan selection +- Country dropdown (NEW - replaces detection) + +**ADD:** ✅ +- Country dropdown with auto-detection default +- Simplified submit that only creates account + +**NEW component structure:** + +```tsx +export default function SignUpFormUnified() { + // State + const [formData, setFormData] = useState({ + email: '', + password: '', + username: '', + first_name: '', + last_name: '', + account_name: '', + billing_country: '', // From dropdown + }); + const [selectedPlan, setSelectedPlan] = useState+ Your {invoice.subscription?.plan?.name} plan is ready to activate +
+Invoice
+#{invoice.invoice_number}
+Amount Due
++ {invoice.currency} {invoice.total_amount} +
++ Pay securely with your credit or debit card via Stripe +
+ ++ Pay securely with your PayPal account +
+ +Payment Required
+Complete your payment to continue using all features
+Credit Balance
+{user?.account?.credits?.toLocaleString()}
+Bank: {bankDetails.bank_name}
+Account Title: {bankDetails.account_title}
+Account #: {bankDetails.account_number}
+IBAN: {bankDetails.iban}
+Reference: {invoiceNumber}
+Amount: {amount}
+No payment methods available for your region
-- 🇵🇰 Pakistan - Bank transfer available -
- )} -+ Your country determines available payment methods +
++ Transfer to the account below and submit your reference +
+Bank
+{bankDetails.bank_name}
+Account Title
+{bankDetails.account_title}
+Account Number
+{bankDetails.account_number}
+IBAN
+{bankDetails.iban}
+Payment Reference (Include in transfer)
+{invoice.invoice_number}
+