diff --git a/docs/plans/DJANGO-ADMIN-ACCESS-GUIDE.md b/docs/90-REFERENCE/DJANGO-ADMIN-ACCESS-GUIDE.md
similarity index 100%
rename from docs/plans/DJANGO-ADMIN-ACCESS-GUIDE.md
rename to docs/90-REFERENCE/DJANGO-ADMIN-ACCESS-GUIDE.md
diff --git a/docs/plans/THIRD-PARTY-INTEGRATIONS-PLAN.md b/docs/plans/implemented/THIRD-PARTY-INTEGRATIONS-PLAN.md
similarity index 100%
rename from docs/plans/THIRD-PARTY-INTEGRATIONS-PLAN.md
rename to docs/plans/implemented/THIRD-PARTY-INTEGRATIONS-PLAN.md
diff --git a/docs/plans/payment-refactor-plan.md b/docs/plans/payment-refactor-plan.md
new file mode 100644
index 00000000..cbda4229
--- /dev/null
+++ b/docs/plans/payment-refactor-plan.md
@@ -0,0 +1,2365 @@
+# 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<Plan | null>(null);
+  const [countries, setCountries] = useState<Country[]>([]);
+  const [detectedCountry, setDetectedCountry] = useState('US');
+
+  // Load countries and detect user's country
+  useEffect(() => {
+    loadCountries();
+    detectUserCountry();
+  }, []);
+
+  const loadCountries = async () => {
+    const response = await fetch(`${API_BASE_URL}/v1/auth/countries/`);
+    const data = await response.json();
+    setCountries(data.countries);
+  };
+
+  const detectUserCountry = async () => {
+    try {
+      // Use IP-based detection (optional - fallback to US)
+      const response = await fetch('https://ipapi.co/json/');
+      const data = await response.json();
+      setDetectedCountry(data.country_code || 'US');
+      setFormData(prev => ({ ...prev, billing_country: data.country_code || 'US' }));
+    } catch {
+      setDetectedCountry('US');
+      setFormData(prev => ({ ...prev, billing_country: 'US' }));
+    }
+  };
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+
+    try {
+      // Register - NO payment redirect
+      const result = await register({
+        ...formData,
+        plan_slug: selectedPlan?.slug || 'free',
+      });
+
+      // Always navigate to plans page
+      // For paid plans: will show PendingPaymentView
+      // For free plan: will show ActiveSubscriptionView
+      if (selectedPlan && selectedPlan.price > 0) {
+        navigate('/account/plans');
+        toast.info('Complete your payment to activate your plan');
+      } else {
+        navigate('/dashboard');
+        toast.success('Welcome to IGNY8!');
+      }
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* Email, Password, Name fields */}
+
+      {/* Country Dropdown - NEW */}
+      <Select
+        label="Country"
+        value={formData.billing_country}
+        onChange={(value) => setFormData({ ...formData, billing_country: value })}
+        options={countries.map(c => ({ value: c.code, label: c.name }))}
+      />
+
+      {/* Plan Selection */}
+      <PlanSelector
+        plans={plans}
+        selectedPlan={selectedPlan}
+        onSelect={setSelectedPlan}
+      />
+
+      {/* Submit Button - Different text based on plan */}
+      <Button type="submit" loading={loading}>
+        {selectedPlan?.price > 0 ? 'Continue to Payment' : 'Create Free Account'}
+      </Button>
+    </form>
+  );
+}
+```
+
+---
+
+### 2.2 Remove /signup/pk Route ✅
+
+**File:** `frontend/src/routes/index.tsx` (or equivalent)
+
+**REMOVE:** ✅
+```tsx
+// DELETE THIS ROUTE
+<Route path="/signup/pk" element={<SignupPage isPakistan />} />
+```
+
+**KEEP only:** ✅
+```tsx
+<Route path="/signup" element={<SignupPage />} />
+```
+
+---
+
+### 2.3 Remove Country Detection API Usage ✅
+
+**Files to update:** ✅
+- `frontend/src/components/auth/SignUpFormUnified.tsx` - Remove ipapi.co calls for complex detection
+- `frontend/src/services/billing.api.ts` - Remove `detectCountry()` function if exists
+
+**NEW approach:** Simple IP-based detection for dropdown default only: ✅
+
+```tsx
+// Simple one-liner for default selection
+const detectCountry = async () => {
+  try {
+    const res = await fetch('https://ipapi.co/country_code/');
+    return await res.text();
+  } catch {
+    return 'US';
+  }
+};
+```
+
+---
+
+### 2.4 Refactor PlansAndBillingPage.tsx ✅
+
+**File:** `frontend/src/pages/account/PlansAndBillingPage.tsx`
+
+**NEW structure:** ✅
+
+```tsx
+export default function PlansAndBillingPage() {
+  const { user, refreshUser } = useAuthStore();
+  const [loading, setLoading] = useState(true);
+  const [invoices, setInvoices] = useState<Invoice[]>([]);
+  const [payments, setPayments] = useState<Payment[]>([]);
+
+  const accountStatus = user?.account?.status;
+  const billingCountry = user?.account?.billing_country;
+
+  // Determine if user has ever paid
+  const hasEverPaid = payments.some(p => p.status === 'succeeded');
+
+  // Determine view mode
+  const isNewUserPendingPayment = accountStatus === 'pending_payment' && !hasEverPaid;
+
+  useEffect(() => {
+    loadBillingData();
+  }, []);
+
+  if (loading) return <LoadingSpinner />;
+
+  // NEW USER - Show full-page payment view
+  if (isNewUserPendingPayment) {
+    return (
+      <PendingPaymentView
+        invoice={invoices.find(i => i.status === 'pending')}
+        userCountry={billingCountry}
+        onPaymentSuccess={() => {
+          refreshUser();
+          loadBillingData();
+        }}
+      />
+    );
+  }
+
+  // EXISTING USER - Show normal billing dashboard
+  return (
+    <ActiveSubscriptionView
+      user={user}
+      invoices={invoices}
+      payments={payments}
+      hasPendingInvoice={invoices.some(i => i.status === 'pending')}
+      onRefresh={loadBillingData}
+    />
+  );
+}
+```
+
+---
+
+### 2.5 Create PendingPaymentView Component ✅
+
+**File:** `frontend/src/components/billing/PendingPaymentView.tsx` (NEW) ✅
+
+```tsx
+interface PendingPaymentViewProps {
+  invoice: Invoice | null;
+  userCountry: string;
+  onPaymentSuccess: () => void;
+}
+
+export default function PendingPaymentView({
+  invoice,
+  userCountry,
+  onPaymentSuccess,
+}: PendingPaymentViewProps) {
+  const isPakistan = userCountry?.toUpperCase() === 'PK';
+
+  // Payment methods based on country
+  const availableMethods: PaymentMethod[] = isPakistan
+    ? ['stripe', 'bank_transfer']
+    : ['stripe', 'paypal'];
+
+  const [selectedMethod, setSelectedMethod] = useState<PaymentMethod>(availableMethods[0]);
+  const [loading, setLoading] = useState(false);
+  const [bankDetails, setBankDetails] = useState<BankDetails | null>(null);
+
+  // Load bank details for PK users
+  useEffect(() => {
+    if (isPakistan) {
+      loadBankDetails();
+    }
+  }, [isPakistan]);
+
+  const loadBankDetails = async () => {
+    const response = await fetch(
+      `${API_BASE_URL}/v1/billing/payment-configs/payment-methods/?country_code=PK&payment_method=bank_transfer`
+    );
+    const data = await response.json();
+    if (data.results?.length > 0) {
+      setBankDetails(data.results[0]);
+    }
+  };
+
+  const handleStripePayment = async () => {
+    setLoading(true);
+    try {
+      const result = await subscribeToPlan(invoice.subscription.plan.slug, 'stripe', {
+        return_url: `${window.location.origin}/account/plans?success=true`,
+        cancel_url: `${window.location.origin}/account/plans?canceled=true`,
+      });
+      window.location.href = result.redirect_url;
+    } catch (err) {
+      toast.error(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handlePayPalPayment = async () => {
+    setLoading(true);
+    try {
+      const result = await subscribeToPlan(invoice.subscription.plan.slug, 'paypal', {
+        return_url: `${window.location.origin}/account/plans?paypal=success`,
+        cancel_url: `${window.location.origin}/account/plans?paypal=cancel`,
+      });
+      window.location.href = result.redirect_url;
+    } catch (err) {
+      toast.error(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleBankTransferSubmit = async (formData: BankTransferFormData) => {
+    setLoading(true);
+    try {
+      await submitManualPayment({
+        invoice_id: invoice.id,
+        payment_method: 'bank_transfer',
+        amount: invoice.total_amount,
+        manual_reference: formData.reference,
+        manual_notes: formData.notes,
+        proof_url: formData.proofUrl,
+      });
+      toast.success('Payment submitted for approval');
+      onPaymentSuccess();
+    } catch (err) {
+      toast.error(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  if (!invoice) {
+    return <div>No pending invoice found</div>;
+  }
+
+  return (
+    <div className="max-w-2xl mx-auto py-12 px-4">
+      {/* Header */}
+      <div className="text-center mb-8">
+        <h1 className="text-3xl font-bold text-gray-900 dark:text-white">
+          Complete Your Subscription
+        </h1>
+        <p className="mt-2 text-gray-600 dark:text-gray-400">
+          Your {invoice.subscription?.plan?.name} plan is ready to activate
+        </p>
+      </div>
+
+      {/* Invoice Summary Card */}
+      <Card className="mb-6">
+        <div className="flex justify-between items-center">
+          <div>
+            <p className="text-sm text-gray-500">Invoice</p>
+            <p className="font-medium">#{invoice.invoice_number}</p>
+          </div>
+          <div className="text-right">
+            <p className="text-sm text-gray-500">Amount Due</p>
+            <p className="text-2xl font-bold">
+              {invoice.currency} {invoice.total_amount}
+            </p>
+          </div>
+        </div>
+        <div className="mt-4 pt-4 border-t">
+          <div className="flex justify-between text-sm">
+            <span className="text-gray-500">Plan</span>
+            <span>{invoice.subscription?.plan?.name}</span>
+          </div>
+          <div className="flex justify-between text-sm mt-1">
+            <span className="text-gray-500">Billing Period</span>
+            <span>Monthly</span>
+          </div>
+        </div>
+      </Card>
+
+      {/* Payment Method Selection */}
+      <Card className="mb-6">
+        <h3 className="font-semibold mb-4">Select Payment Method</h3>
+        <div className="flex gap-3">
+          {availableMethods.map((method) => (
+            <button
+              key={method}
+              onClick={() => setSelectedMethod(method)}
+              className={`flex-1 p-4 rounded-lg border-2 transition-all ${
+                selectedMethod === method
+                  ? 'border-brand-500 bg-brand-50'
+                  : 'border-gray-200 hover:border-gray-300'
+              }`}
+            >
+              {method === 'stripe' && <CreditCardIcon className="w-6 h-6 mx-auto mb-2" />}
+              {method === 'paypal' && <WalletIcon className="w-6 h-6 mx-auto mb-2" />}
+              {method === 'bank_transfer' && <Building2Icon className="w-6 h-6 mx-auto mb-2" />}
+              <span className="block text-sm font-medium">
+                {method === 'stripe' && 'Credit/Debit Card'}
+                {method === 'paypal' && 'PayPal'}
+                {method === 'bank_transfer' && 'Bank Transfer'}
+              </span>
+            </button>
+          ))}
+        </div>
+      </Card>
+
+      {/* Payment Form */}
+      <Card>
+        {selectedMethod === 'stripe' && (
+          <div className="text-center py-6">
+            <CreditCardIcon className="w-12 h-12 mx-auto text-brand-500 mb-4" />
+            <p className="text-gray-600 mb-4">
+              Pay securely with your credit or debit card via Stripe
+            </p>
+            <Button
+              variant="primary"
+              onClick={handleStripePayment}
+              loading={loading}
+              className="w-full"
+            >
+              Pay {invoice.currency} {invoice.total_amount}
+            </Button>
+          </div>
+        )}
+
+        {selectedMethod === 'paypal' && (
+          <div className="text-center py-6">
+            <WalletIcon className="w-12 h-12 mx-auto text-[#0070ba] mb-4" />
+            <p className="text-gray-600 mb-4">
+              Pay securely with your PayPal account
+            </p>
+            <Button
+              variant="primary"
+              onClick={handlePayPalPayment}
+              loading={loading}
+              className="w-full bg-[#0070ba] hover:bg-[#005ea6]"
+            >
+              Pay with PayPal
+            </Button>
+          </div>
+        )}
+
+        {selectedMethod === 'bank_transfer' && (
+          <BankTransferForm
+            bankDetails={bankDetails}
+            invoiceNumber={invoice.invoice_number}
+            amount={`${invoice.currency} ${invoice.total_amount}`}
+            onSubmit={handleBankTransferSubmit}
+            loading={loading}
+          />
+        )}
+      </Card>
+
+      {/* Change Plan Link */}
+      <div className="mt-6 text-center">
+        <button
+          onClick={() => setShowPlanSelector(true)}
+          className="text-sm text-gray-500 hover:text-gray-700"
+        >
+          Need a different plan?
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+### 2.6 Create ActiveSubscriptionView Component
+
+**Status:** Existing PlansAndBillingPage.tsx serves this purpose - no separate component needed.
+The current implementation now conditionally renders PendingPaymentView for new users, 
+and the full billing dashboard (effectively "ActiveSubscriptionView") for existing users.
+
+**File:** `frontend/src/pages/account/views/ActiveSubscriptionView.tsx` (NEW)
+
+This is the cleaned-up version of current PlansAndBillingPage with:
+- Proper state handling
+- Correct badge colors
+- Disabled buttons based on state
+- Payment modal only for credits and overdue invoices
+
+```tsx
+export default function ActiveSubscriptionView({
+  user,
+  invoices,
+  payments,
+  hasPendingInvoice,
+  onRefresh,
+}: ActiveSubscriptionViewProps) {
+  const accountStatus = user?.account?.status;
+  const subscription = user?.account?.subscription;
+
+  // Get subscription display
+  const getSubscriptionDisplay = () => {
+    if (!subscription) return { label: 'No Plan', tone: 'error' as const };
+
+    switch (subscription.status) {
+      case 'active':
+        return hasPendingInvoice
+          ? { label: 'Payment Due', tone: 'warning' as const }
+          : { label: 'Active', tone: 'success' as const };
+      case 'pending_payment':
+        return { label: 'Awaiting Payment', tone: 'warning' as const };
+      case 'past_due':
+        return { label: 'Payment Overdue', tone: 'error' as const };
+      case 'canceled':
+        return { label: 'Cancels Soon', tone: 'warning' as const };
+      default:
+        return { label: subscription.status, tone: 'neutral' as const };
+    }
+  };
+
+  const statusDisplay = getSubscriptionDisplay();
+
+  // Can user perform actions?
+  const canUpgrade = accountStatus === 'active' && !hasPendingInvoice;
+  const canBuyCredits = accountStatus === 'active' && !hasPendingInvoice;
+  const canCancel = accountStatus === 'active' && !hasPendingInvoice;
+  const canManageBilling = user?.account?.stripe_customer_id && canUpgrade;
+
+  return (
+    <div className="space-y-6">
+      {/* Pending Payment Banner for existing users */}
+      {hasPendingInvoice && (
+        <Alert variant="warning">
+          <div className="flex items-center justify-between">
+            <div>
+              <p className="font-medium">Payment Required</p>
+              <p className="text-sm">Complete your payment to continue using all features</p>
+            </div>
+            <Button
+              variant="primary"
+              size="sm"
+              onClick={() => setShowPaymentModal(true)}
+            >
+              Pay Now
+            </Button>
+          </div>
+        </Alert>
+      )}
+
+      {/* Current Plan Card */}
+      <Card>
+        <div className="flex items-center justify-between">
+          <div>
+            <h2 className="text-lg font-semibold">{user?.account?.plan?.name}</h2>
+            <Badge variant="solid" tone={statusDisplay.tone}>
+              {statusDisplay.label}
+            </Badge>
+          </div>
+          <div className="flex gap-2">
+            {canManageBilling && (
+              <Button variant="outline" onClick={handleManageBilling}>
+                Manage Billing
+              </Button>
+            )}
+            {canUpgrade && (
+              <Button variant="primary" onClick={() => setShowUpgradeModal(true)}>
+                Upgrade
+              </Button>
+            )}
+          </div>
+        </div>
+      </Card>
+
+      {/* Credits Card */}
+      <Card>
+        <div className="flex items-center justify-between">
+          <div>
+            <p className="text-sm text-gray-500">Credit Balance</p>
+            <p className="text-2xl font-bold">{user?.account?.credits?.toLocaleString()}</p>
+          </div>
+          {canBuyCredits && (
+            <Button variant="outline" onClick={() => setShowCreditsModal(true)}>
+              Buy Credits
+            </Button>
+          )}
+        </div>
+      </Card>
+
+      {/* Billing History */}
+      <Card>
+        <h3 className="font-semibold mb-4">Billing History</h3>
+        <InvoiceTable invoices={invoices} />
+      </Card>
+
+      {/* Cancel Subscription - only for active paid users */}
+      {canCancel && subscription && (
+        <div className="text-center">
+          <button
+            onClick={() => setShowCancelModal(true)}
+            className="text-sm text-gray-500 hover:text-error-500"
+          >
+            Cancel Subscription
+          </button>
+        </div>
+      )}
+
+      {/* Modals */}
+      <PayInvoiceModal
+        isOpen={showPaymentModal}
+        onClose={() => setShowPaymentModal(false)}
+        invoice={invoices.find(i => i.status === 'pending')}
+        userCountry={user?.account?.billing_country}
+        onSuccess={onRefresh}
+      />
+
+      <BuyCreditsModal
+        isOpen={showCreditsModal}
+        onClose={() => setShowCreditsModal(false)}
+        userCountry={user?.account?.billing_country}
+        onSuccess={onRefresh}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+### 2.7 Update BankTransferForm to Load Details from Backend ✅
+
+**File:** `frontend/src/components/billing/BankTransferForm.tsx` ✅
+
+**REMOVE:** Hardcoded bank details ✅
+
+**ADD:** Props for bank details from parent: ✅
+
+```tsx
+interface BankTransferFormProps {
+  bankDetails: {
+    bank_name: string;
+    account_title: string;
+    account_number: string;
+    iban: string;
+    swift_code: string;
+  } | null;
+  invoiceNumber: string;
+  amount: string;
+  onSubmit: (data: BankTransferFormData) => void;
+  loading: boolean;
+}
+
+export default function BankTransferForm({
+  bankDetails,
+  invoiceNumber,
+  amount,
+  onSubmit,
+  loading,
+}: BankTransferFormProps) {
+  if (!bankDetails) {
+    return <LoadingSpinner />;
+  }
+
+  return (
+    <div className="space-y-4">
+      {/* Bank Details - FROM BACKEND */}
+      <div className="p-4 bg-blue-50 rounded-lg">
+        <h4 className="font-medium mb-2">Bank Transfer Details</h4>
+        <div className="text-sm space-y-1">
+          <p><span className="font-medium">Bank:</span> {bankDetails.bank_name}</p>
+          <p><span className="font-medium">Account Title:</span> {bankDetails.account_title}</p>
+          <p><span className="font-medium">Account #:</span> {bankDetails.account_number}</p>
+          <p><span className="font-medium">IBAN:</span> {bankDetails.iban}</p>
+          <p><span className="font-medium">Reference:</span> {invoiceNumber}</p>
+          <p><span className="font-medium">Amount:</span> {amount}</p>
+        </div>
+      </div>
+
+      {/* Form fields */}
+      {/* ... */}
+    </div>
+  );
+}
+```
+
+---
+
+### 2.8 Remove PendingPaymentBanner.tsx
+
+**File:** `frontend/src/components/billing/PendingPaymentBanner.tsx`
+
+**ACTION:** KEPT - Still useful for showing on other pages (dashboard, etc.)
+The full-page `PendingPaymentView` replaces this for the /account/plans page when dealing with new users.
+For existing users with missed payments, the banner can still appear on other pages.
+
+---
+
+### 2.9 Clean Up billing.api.ts ✅
+
+**File:** `frontend/src/services/billing.api.ts`
+
+**REMOVE:**
+- `detectCountry()` function if exists - ✅ Not found (never existed)
+- Any unused payment config functions
+
+**KEEP:** ✅
+- All gateway functions (Stripe, PayPal)
+- Invoice/Payment CRUD
+- `subscribeToPlan()` and `purchaseCredits()` helpers
+
+---
+
+### 2.10 Clean Up authStore.ts ✅
+
+**File:** `frontend/src/store/authStore.ts`
+
+**UPDATE register() to NOT expect checkout_url:** ✅
+
+```tsx
+register: async (registerData) => {
+  const response = await fetch(`${API_BASE_URL}/v1/auth/register/`, {
+    method: 'POST',
+    body: JSON.stringify({
+      email: registerData.email,
+      password: registerData.password,
+      username: registerData.username,
+      first_name: registerData.first_name,
+      last_name: registerData.last_name,
+      account_name: registerData.account_name,
+      plan_slug: registerData.plan_slug,
+      billing_country: registerData.billing_country,
+    }),
+  });
+
+  const data = await response.json();
+
+  if (!response.ok) {
+    throw new Error(data.error || 'Registration failed');
+  }
+
+  // Set auth state
+  set({
+    user: data.user,
+    token: data.tokens.access,
+    refreshToken: data.tokens.refresh,
+    isAuthenticated: true,
+  });
+
+  return data.user;  // NO checkout_url
+}
+```
+
+---
+
+## Phase 3: Remove Dead Code & Fields ✅
+
+### 3.1 Backend - Remove Unused Fields
+
+**File:** `backend/igny8_core/auth/models.py`
+
+Consider removing if truly unused (verify first):
+- Any temporary migration fields
+
+**Status:** Deferred - no critical dead code identified
+
+### 3.2 Backend - Clean Up Unused Code in RegisterSerializer ✅
+
+**File:** `backend/igny8_core/auth/urls.py`
+
+**REMOVE:** ✅
+- Stripe checkout session creation code - REMOVED
+- PayPal order creation code - REMOVED
+- All `checkout_url` generation logic - REMOVED
+
+### 3.3 Frontend - Remove Files ✅
+
+**DELETE these files:**
+- `frontend/src/pages/AuthPages/SignUpPK.tsx` - ✅ DELETED
+- Any country detection utility files - None found
+
+**Status:** SignUpPK.tsx deleted successfully
+
+### 3.4 Frontend - Remove Unused Routes ✅
+
+**File:** Routes configuration
+
+**REMOVE:** ✅
+```tsx
+<Route path="/signup/pk" ... />
+```
+**Done:** Route now redirects to main SignUp component
+
+---
+
+## Phase 4: Database Migrations ✅
+
+### 4.1 Create Migration for WebhookEvent Model ✅
+
+```bash
+python manage.py makemigrations billing --name add_webhook_event_model
+python manage.py migrate
+```
+
+**Done:** Migration 0029_add_webhook_event_and_manual_reference_constraint applied
+
+### 4.2 Create Migration for Manual Reference Uniqueness ✅
+
+```bash
+python manage.py makemigrations billing --name make_manual_reference_unique
+python manage.py migrate
+```
+
+**Done:** Included in migration 0029
+
+---
+
+## Phase 5: Testing Checklist (Manual Testing Required)
+
+### 5.1 Signup Flow Tests
+
+- [ ] Signup with free plan → redirects to dashboard/sites
+- [ ] Signup with paid plan → redirects to /account/plans
+- [ ] Signup page shows country dropdown with auto-detection
+- [ ] Country dropdown shows all countries from backend
+- [ ] No payment method selection on signup page
+
+### 5.2 PendingPaymentView Tests (New Users)
+
+- [ ] Shows for new user with `pending_payment` status
+- [ ] Shows correct invoice details and plan name
+- [ ] Shows Stripe + PayPal for global users
+- [ ] Shows Stripe + Bank Transfer for PK users
+- [ ] Stripe payment redirects and returns correctly
+- [ ] PayPal payment redirects and returns correctly
+- [ ] Bank transfer form submits correctly
+- [ ] Bank details loaded from backend (not hardcoded)
+
+### 5.3 ActiveSubscriptionView Tests (Existing Users)
+
+- [ ] Shows for users who have paid before
+- [ ] Shows pending payment banner if invoice overdue
+- [ ] Upgrade button disabled when payment pending
+- [ ] Cancel button only shows for active subscriptions
+- [ ] Manage Billing only shows for Stripe users
+- [ ] Credit purchase works via modal
+- [ ] Invoice payment works via modal
+
+### 5.4 Webhook Tests
+
+- [ ] Stripe webhook processes only once (idempotency)
+- [ ] PayPal webhook validates signature
+- [ ] PayPal capture only processes once (idempotency)
+- [ ] PayPal amount validation catches mismatches
+- [ ] Webhook events stored in WebhookEvent model
+
+### 5.5 Security Tests
+
+- [ ] Invalid PayPal webhook signature returns 400
+- [ ] Duplicate Stripe webhook doesn't create duplicate payment
+- [ ] Duplicate PayPal capture returns already_captured response
+- [ ] Amount manipulation in PayPal returns error
+
+---
+
+## Implementation Order
+
+### Day 1: Backend Security Fixes
+1. Enable PayPal webhook signature verification
+2. Add Stripe webhook idempotency
+3. Add PayPal capture idempotency
+4. Add PayPal amount validation
+5. Fix refund module imports
+6. Add WebhookEvent model
+7. Run migrations
+
+### Day 2: Backend Simplification
+1. Simplify RegisterSerializer (remove checkout creation)
+2. Simplify RegisterView (remove checkout_url response)
+3. Add CountryListView endpoint
+4. Add manual_reference uniqueness migration
+5. Test registration flow
+
+### Day 3: Frontend Signup Simplification
+1. Simplify SignUpFormUnified.tsx
+2. Remove /signup/pk route
+3. Update authStore register function
+4. Test signup flow for all plans
+
+### Day 4: Frontend Plans Page Refactor
+1. Create PendingPaymentView component
+2. Create ActiveSubscriptionView component
+3. Refactor PlansAndBillingPage to use new views
+4. Update BankTransferForm to use backend details
+5. Test new user payment flow
+
+### Day 5: Cleanup & Testing
+1. Remove PendingPaymentBanner (or repurpose)
+2. Clean up billing.api.ts
+3. Remove dead code
+4. Full integration testing
+5. Update documentation
+
+---
+
+## Files Changed Summary
+
+### Backend Files to Modify
+| File | Changes |
+|------|---------|
+| `views/paypal_views.py` | Enable signature verification, add idempotency, add amount validation |
+| `views/stripe_views.py` | Add idempotency check |
+| `views/refund_views.py` | Fix imports |
+| `models.py` | Add WebhookEvent model |
+| `auth/serializers.py` | Remove checkout creation |
+| `auth/views.py` | Remove checkout_url, add CountryListView |
+| `auth/urls.py` | Add countries/ endpoint |
+
+### Backend Migrations
+| Migration | Purpose |
+|-----------|---------|
+| `add_webhook_event_model` | Audit trail for webhooks |
+| `make_manual_reference_unique` | Prevent duplicate references |
+
+### Frontend Files to Modify
+| File | Changes |
+|------|---------|
+| `SignUpFormUnified.tsx` | Remove payment selection, add country dropdown |
+| `PlansAndBillingPage.tsx` | Refactor to use new view components |
+| `authStore.ts` | Remove checkout_url handling |
+| `billing.api.ts` | Clean up unused functions |
+
+### Frontend Files to Create
+| File | Purpose |
+|------|---------|
+| `views/PendingPaymentView.tsx` | Full-page payment for new users |
+| `views/ActiveSubscriptionView.tsx` | Dashboard for existing users |
+| `components/BankTransferForm.tsx` | Reusable bank transfer form |
+
+### Frontend Files to Delete
+| File | Reason |
+|------|--------|
+| Route for `/signup/pk` | Consolidated into single signup |
+| `PendingPaymentBanner.tsx` | Replaced by PendingPaymentView (optional - may keep for other pages) |
+
+---
+
+## Verification Commands
+
+### Backend Verification
+
+```bash
+# Test Stripe config
+curl http://localhost:8000/v1/billing/stripe/config/ -H "Authorization: Bearer $TOKEN"
+
+# Test PayPal config
+curl http://localhost:8000/v1/billing/paypal/config/ -H "Authorization: Bearer $TOKEN"
+
+# Test country list
+curl http://localhost:8000/v1/auth/countries/
+
+# Test registration (no checkout_url in response)
+curl -X POST http://localhost:8000/v1/auth/register/ \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@test.com","password":"test123","plan_slug":"starter","billing_country":"US"}'
+```
+
+### Frontend Verification
+
+```bash
+# Build check
+npm run build
+
+# Type check
+npm run typecheck
+
+# Lint
+npm run lint
+```
+
+---
+
+## Success Criteria
+
+1. **Signup flow simplified** - No payment redirect from signup
+2. **Single payment interface** - All payments through /account/plans
+3. **Security issues fixed** - Webhook verification, idempotency
+
+---
+
+# 🚨 CRITICAL ISSUES AFTER REFACTOR
+
+## 🔴 **NEW CRITICAL BUGS INTRODUCED IN RECENT REFACTORS**
+
+### Issue #1: Payment Gateway Country Filtering Broken
+
+| # | Severity | Issue | Location | Line |
+|---|----------|-------|----------|------|
+| 1 | 🔴 CRITICAL | `getAvailablePaymentGateways()` called **without country code** - returns PayPal for ALL users including PK | PlansAndBillingPage.tsx | ~251 |
+| 2 | 🔴 CRITICAL | `getAvailablePaymentGateways()` called **without country code** in PaymentGatewaySelector | PaymentGatewaySelector.tsx | - |
+| 3 | 🔴 CRITICAL | `availableGateways` initialized with `manual: true` (Bank Transfer shows for ALL users by default) | PlansAndBillingPage.tsx | - |
+| 4 | 🔴 CRITICAL | PayPal button visible in Buy Credits section for PK users | PlansAndBillingPage.tsx | - |
+| 5 | 🔴 CRITICAL | PayPal button visible in Upgrade Modal for PK users | PlansAndBillingPage.tsx | - |
+| 6 | 🔴 CRITICAL | Bank Transfer button visible in Upgrade Modal for NON-PK users | PlansAndBillingPage.tsx | - |
+
+**Root Cause:**
+```tsx
+// CURRENT (BROKEN) - Line ~251:
+const gateways = await getAvailablePaymentGateways();
+
+// SHOULD BE:
+const billingCountry = user?.account?.billing_country || 'US';
+const gateways = await getAvailablePaymentGateways(billingCountry);
+```
+
+**Impact:** 
+- PK users can see and attempt PayPal payments (NOT ALLOWED)
+- Non-PK users see Bank Transfer option (WRONG)
+- Payment method selection doesn't respect country restrictions
+
+---
+
+### Issue #2: Stripe Return Flow Broken After Refactor
+
+**Status:** 🔴 **BROKEN** - Payments not activating accounts
+
+**Evidence:**
+- User completes payment on Stripe
+- Stripe redirects to `/account/plans?success=true`
+- Invoice remains `status='pending'`
+- Account remains `status='pending_payment'`
+- Notification shows "payment successful" but account not activated
+
+**Root Cause:**
+1. Frontend redirect URL changed from `/plans` to `/account/plans`
+2. No backend endpoint to handle return URL verification
+3. Relies entirely on webhook which may be delayed
+4. Frontend has no way to force-check payment status
+
+**Missing Flow:**
+```
+User Returns → Check URL params → ❌ NO BACKEND CALL
+                                 → ❌ No status verification
+                                 → Shows old cached status
+```
+
+**Should Be:**
+```
+User Returns → Extract session_id from URL 
+            → Call /v1/billing/verify-payment-status/?session_id=xxx
+            → Backend checks with Stripe
+            → Return updated account/subscription status
+            → Refresh UI
+```
+
+---
+
+### Issue #3: PayPal Return Flow Broken After Refactor
+
+**Status:** 🔴 **BROKEN** - "Payment not captured" error
+
+**Evidence:**
+- User approves payment on PayPal
+- PayPal redirects to `/account/plans?paypal=success&token=xxx`
+- Frontend shows "Payment not captured" error
+- Order remains uncaptured
+
+**Root Cause:**
+1. Frontend expects to call `/v1/billing/paypal/capture-order/` on return
+2. But `order_id` is not in URL params (PayPal uses `token` param)
+3. Capture endpoint requires `order_id` not `token`
+4. Mismatch between PayPal redirect params and capture endpoint
+
+**Current Broken Flow:**
+```
+PayPal Redirect → ?paypal=success&token=EC-xxx
+                → Frontend tries to extract order_id
+                → ❌ No order_id in URL
+                → ❌ Capture fails
+```
+
+**Should Be:**
+```
+PayPal Redirect → ?paypal=success&token=EC-xxx
+                → Frontend stores order_id before redirect
+                → On return, retrieve order_id from storage
+                → Call capture with correct order_id
+```
+
+---
+
+### Issue #4: Invoice Currency Mismatch
+
+| # | Severity | Issue | Location |
+|---|----------|-------|----------|
+| 7 | 🟡 HIGH | Buy Credits always shows `$` (USD) even for PK users using Bank Transfer (should show PKR) | PlansAndBillingPage.tsx |
+| 8 | 🟡 HIGH | Quick Upgrade cards always show `$` (USD) for all users | PlansAndBillingPage.tsx |
+| 9 | 🟡 HIGH | Upgrade Modal shows `$` for all plans even when Bank Transfer (PKR) selected | PlansAndBillingPage.tsx |
+| 10 | 🟢 MEDIUM | Invoice created with currency depends on `account.payment_method` which may not be set at signup | invoice_service.py |
+
+**Root Cause:**
+- Invoice currency determined at creation time based on `account.payment_method`
+- At signup, `account.payment_method` may not be set
+- Frontend hardcodes `$` symbol
+- No dynamic currency switching based on selected gateway
+
+---
+
+### Issue #5: "Manage Billing" Logic Error
+
+| # | Severity | Issue | Location |
+|---|----------|-------|----------|
+| 11 | 🟡 HIGH | "Manage Billing" shows for users with Stripe available, not users who **paid via Stripe** | PlansAndBillingPage.tsx |
+
+**Root Cause:**
+```tsx
+// CURRENT (WRONG):
+const canManageBilling = availableGateways.stripe && hasActivePlan;
+
+// SHOULD BE:
+const canManageBilling = user?.account?.payment_method === 'stripe' 
+                      && user?.account?.stripe_customer_id
+                      && hasActivePlan;
+```
+
+**Impact:** 
+- PK users who paid via Bank Transfer see "Manage Billing" button
+- Clicking it tries to redirect to Stripe portal (which doesn't exist for them)
+
+---
+
+### Issue #6: Plan Status Display Logic Error
+
+| # | Audit Issue | Claimed Status | Actual Status |
+|---|-------------|----------------|---------------|
+| 1 | Plan shows "Active" even with unpaid invoice | ✅ Claimed fixed | ❌ Still using `hasActivePlan` based on plan existence only |
+| 2 | "Manage Billing" shown to non-Stripe users | ✅ Claimed fixed | ❌ Shows for anyone with `availableGateways.stripe` |
+| 3 | Cancel Subscription available when account pending | ✅ Claimed fixed | ❌ Logic not properly implemented |
+| 4 | Payment gateway selection not synced with account | ✅ Claimed fixed | ❌ Gateway determined without country |
+
+**Root Cause:**
+```tsx
+// CURRENT (WRONG):
+const hasActivePlan = !!user?.account?.plan && user?.account?.plan?.slug !== 'free';
+
+// SHOULD CHECK:
+const hasActivePlan = user?.account?.status === 'active' 
+                   && user?.account?.plan?.slug !== 'free'
+                   && !hasPendingInvoice;
+```
+
+---
+
+### Issue #7: Backend Payment Method Endpoint Returns Wrong Data
+
+| # | Severity | Issue | Location |
+|---|----------|-------|----------|
+| 12 | 🟢 MEDIUM | Backend `list_payment_methods` endpoint returns ALL enabled methods ignoring country_code | billing_views.py |
+
+**Evidence:**
+```python
+# Current endpoint ignores country filtering
+def list_payment_methods(request):
+    methods = PaymentMethodConfig.objects.filter(is_enabled=True)
+    # ❌ No country-based filtering
+    return Response(methods)
+```
+
+**Should Be:**
+```python
+def list_payment_methods(request):
+    country = request.query_params.get('country_code', 'US')
+    methods = PaymentMethodConfig.objects.filter(
+        is_enabled=True,
+        country_code=country
+    )
+    return Response(methods)
+```
+
+---
+
+## 🔴 **CRITICAL: Payment Return Flows NOT WORKING**
+
+### Stripe Return Flow - BROKEN ❌
+
+**Current State:**
+```
+User pays on Stripe
+    ↓
+Stripe redirects to: /account/plans?success=true&session_id=cs_xxx
+    ↓
+Frontend PlansAndBillingPage loads
+    ↓
+❌ NO API CALL to verify payment
+    ↓
+Shows cached user data (still pending_payment)
+    ↓
+User sees "Complete your payment" (even though they just paid)
+    ↓
+Webhook eventually fires (5-30 seconds later)
+    ↓
+Page doesn't auto-refresh
+    ↓
+User must manually refresh to see activation
+```
+
+**What's Missing:**
+1. No `/v1/billing/verify-stripe-return/` endpoint
+2. Frontend doesn't extract `session_id` from URL
+3. No status polling/refresh mechanism
+4. No loading state while verification happens
+
+---
+
+### PayPal Return Flow - BROKEN ❌
+
+**Current State:**
+```
+User approves on PayPal
+    ↓
+PayPal redirects to: /account/plans?paypal=success&token=EC-xxx&PayerID=yyy
+    ↓
+Frontend tries to capture payment
+    ↓
+❌ Can't find order_id (only has token)
+    ↓
+Capture API call fails
+    ↓
+Shows error: "Payment not captured"
+    ↓
+User stuck with pending payment
+```
+
+**What's Missing:**
+1. `order_id` not persisted before redirect
+2. No mapping from `token` → `order_id`
+3. Capture endpoint can't proceed without `order_id`
+
+---
+
+### Bank Transfer Flow - Working ✅
+
+**Current State:** (This one works correctly)
+```
+User submits bank transfer proof
+    ↓
+POST /v1/billing/payments/manual/
+    ↓
+Creates Payment record (status=pending)
+    ↓
+Admin approves payment
+    ↓
+Account activated
+    ↓
+✅ Works as expected
+```
+
+---
+
+## 📊 COMPLETE END-TO-END PAYMENT WORKFLOW DIAGRAMS
+
+### 🔵 STRIPE FLOW - US/GLOBAL USERS (Subscription)
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 1: SIGNUP                                  │
+└────────────────────────────────────────────────────────────────────┘
+
+User visits /signup
+    ↓
+Fills form: email, password, name, country=US, plan=Starter ($29/mo)
+    ↓
+Clicks "Create Account"
+    ↓
+POST /v1/auth/register/
+    └─> Body: {
+            email, password, username,
+            billing_country: 'US',
+            plan_slug: 'starter'
+        }
+
+BACKEND ACTIONS:
+    1. Create User
+    2. Create Account (status='pending_payment', plan=Starter, credits=0)
+    3. Create Subscription (status='pending_payment')
+    4. Create Invoice (status='pending', currency='USD', amount=29.00)
+    5. Return: { user, tokens, ... }  // ❌ NO checkout_url
+
+Frontend redirects to → /account/plans
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 2: PAYMENT PAGE                            │
+└────────────────────────────────────────────────────────────────────┘
+
+/account/plans loads
+    ↓
+Checks: accountStatus='pending_payment' && hasEverPaid=false
+    ↓
+Shows PendingPaymentView
+    ↓
+Displays Invoice #INV-260100001, Amount: $29.00
+    ↓
+Payment methods: [Stripe ✅, PayPal ✅]  (country=US)
+    ↓
+User selects Stripe
+    ↓
+Clicks "Pay $29.00"
+    ↓
+
+POST /v1/billing/stripe/subscribe/
+    └─> Body: {
+            plan_slug: 'starter',
+            payment_method: 'stripe',
+            return_url: 'http://localhost:5173/account/plans?success=true',
+            cancel_url: 'http://localhost:5173/account/plans?canceled=true'
+        }
+
+BACKEND ACTIONS (stripe_views.py - StripeSubscribeView):
+    1. Get plan, account
+    2. Create Stripe Checkout Session
+       - mode: 'subscription'
+       - line_items: [{ price: plan.stripe_price_id, quantity: 1 }]
+       - customer_email: user.email
+       - metadata: { account_id, plan_id, type: 'subscription' }
+       - success_url: return_url
+       - cancel_url: cancel_url
+    3. Return { redirect_url: session.url }
+
+Frontend redirects to → session.url (Stripe hosted page)
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 3: STRIPE PAYMENT                          │
+└────────────────────────────────────────────────────────────────────┘
+
+User on Stripe page
+    ↓
+Enters card details
+    ↓
+Clicks "Pay"
+    ↓
+Stripe processes payment
+    ↓
+Payment succeeds
+    ↓
+Stripe redirects to → /account/plans?success=true&session_id=cs_xxx
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 4: RETURN TO APP (❌ BROKEN)              │
+└────────────────────────────────────────────────────────────────────┘
+
+Browser lands on /account/plans?success=true&session_id=cs_xxx
+    ↓
+PlansAndBillingPage.tsx loads
+    ↓
+useEffect runs → loadBillingData()
+    ↓
+❌ BUG: No code to check URL params for session_id
+❌ BUG: No API call to verify payment status
+❌ BUG: Just loads user data from cache/API (still shows pending)
+    ↓
+User sees: "Complete Your Subscription" (same pending view)
+    ↓
+User confused: "I just paid!"
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 5: WEBHOOK (5-30 SEC LATER)               │
+└────────────────────────────────────────────────────────────────────┘
+
+Stripe sends webhook → POST /v1/billing/stripe/webhook/
+    └─> Event: checkout.session.completed
+
+BACKEND ACTIONS (stripe_views.py - _handle_checkout_completed):
+    ✅ 1. Idempotency check - session_id in Payment.metadata
+    ✅ 2. Get account from metadata
+    ✅ 3. Retrieve Stripe subscription details
+    ✅ 4. Create/Update Subscription record:
+          - status = 'active'
+          - stripe_subscription_id = 'sub_xxx'
+          - current_period_start, current_period_end
+    ✅ 5. Get or create Invoice (prevents duplicates)
+    ✅ 6. Mark Invoice as PAID:
+          - status = 'paid'
+          - paid_at = now
+    ✅ 7. Create Payment record:
+          - status = 'succeeded'
+          - approved_at = now
+          - stripe_payment_intent_id
+          - metadata: { checkout_session_id, subscription_id }
+    ✅ 8. Create/Update AccountPaymentMethod:
+          - type = 'stripe'
+          - is_verified = True
+          - is_default = True
+    ✅ 9. Add credits:
+          - CreditService.add_credits(account, plan.included_credits)
+    ✅ 10. Update Account:
+          - status = 'active'
+          - plan = plan
+    ❌ 11. NO email sent
+    ❌ 12. NO real-time notification to frontend
+
+Returns 200 to Stripe
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 6: USER EXPERIENCE                         │
+└────────────────────────────────────────────────────────────────────┘
+
+User still on /account/plans
+    ↓
+Page shows pending payment (cached data)
+    ↓
+❌ Page doesn't auto-refresh
+❌ No websocket notification
+    ↓
+User must MANUALLY refresh page
+    ↓
+On refresh: loadBillingData() fetches new status
+    ↓
+NOW shows: Active plan, credits added
+    ↓
+✅ Finally works after manual refresh
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    CURRENT BUGS SUMMARY                             │
+└────────────────────────────────────────────────────────────────────┘
+
+🔴 CRITICAL BUGS:
+1. No payment verification on return URL
+2. User sees pending state after successful payment
+3. Requires manual refresh to see activation
+4. No loading/polling state
+5. Poor UX - user thinks payment failed
+
+✅ WORKING CORRECTLY:
+1. Webhook processing
+2. Account activation
+3. Credit addition
+4. Subscription creation
+5. Invoice marking as paid
+```
+
+---
+
+### 🟡 PAYPAL FLOW - US/GLOBAL USERS (Subscription)
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 1-2: SAME AS STRIPE                        │
+└────────────────────────────────────────────────────────────────────┘
+
+(User signup, account creation, redirect to /account/plans)
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 3: PAYPAL ORDER CREATION                   │
+└────────────────────────────────────────────────────────────────────┘
+
+User on /account/plans (PendingPaymentView)
+    ↓
+Selects PayPal
+    ↓
+Clicks "Pay with PayPal"
+    ↓
+
+POST /v1/billing/paypal/subscribe/
+    └─> Body: {
+            plan_slug: 'starter',
+            payment_method: 'paypal',
+            return_url: 'http://localhost:5173/account/plans?paypal=success',
+            cancel_url: 'http://localhost:5173/account/plans?paypal=cancel'
+        }
+
+BACKEND ACTIONS (paypal_views.py - PayPalSubscribeView):
+    1. Get plan, account
+    2. Create PayPal Order:
+       - intent: 'CAPTURE'
+       - purchase_units: [{
+           amount: { currency_code: 'USD', value: '29.00' },
+           custom_id: account.id,
+           description: plan.name
+         }]
+       - application_context: {
+           return_url: return_url,
+           cancel_url: cancel_url
+         }
+    3. Extract order_id from response
+    4. Extract approve link from response.links
+    5. ❌ BUG: order_id NOT stored anywhere for later retrieval
+    6. Return { redirect_url: approve_link }
+
+Frontend:
+    ❌ BUG: Doesn't store order_id before redirect
+    Redirects to → approve_link (PayPal page)
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 4: PAYPAL APPROVAL                         │
+└────────────────────────────────────────────────────────────────────┘
+
+User on PayPal page
+    ↓
+Logs in to PayPal
+    ↓
+Clicks "Approve"
+    ↓
+PayPal redirects to → /account/plans?paypal=success&token=EC-xxx&PayerID=yyy
+    ↓
+❌ BUG: URL has 'token', not 'order_id'
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 5: CAPTURE ATTEMPT (❌ BROKEN)            │
+└────────────────────────────────────────────────────────────────────┘
+
+Browser lands on /account/plans?paypal=success&token=EC-xxx
+    ↓
+PlansAndBillingPage.tsx detects ?paypal=success
+    ↓
+Tries to extract order_id from URL params
+    ↓
+❌ BUG: URL has 'token=EC-xxx', not 'order_id'
+❌ BUG: No code to convert token → order_id
+❌ BUG: No stored order_id from Phase 3
+    ↓
+Calls POST /v1/billing/paypal/capture-order/
+    └─> Body: { order_id: undefined }  // ❌ MISSING
+    ↓
+Backend returns 400: "order_id required"
+    ↓
+Frontend shows: "Payment not captured"
+    ↓
+User stuck with pending payment
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    WHAT SHOULD HAPPEN (IF WORKING)                  │
+└────────────────────────────────────────────────────────────────────┘
+
+Frontend should:
+    1. Store order_id in localStorage before redirect
+    2. On return, retrieve order_id from localStorage
+    3. Call capture with correct order_id
+
+OR:
+
+Backend should:
+    1. Accept token parameter
+    2. Look up order_id from token via PayPal API
+    3. Then proceed with capture
+
+CAPTURE FLOW (paypal_views.py - PayPalCaptureOrderView):
+    ✅ 1. Idempotency check - order_id already captured
+    ✅ 2. Call PayPal API to capture order
+    ✅ 3. Extract payment type from metadata
+    ✅ 4. If subscription:
+          - _process_subscription_payment()
+          - Create Subscription (status='active')
+          - Create Invoice
+          - Mark Invoice paid
+          - Create Payment record
+          - Create AccountPaymentMethod (type='paypal')
+          - Add credits
+          - Activate account
+    ✅ 5. Return success
+
+But currently this never executes due to missing order_id.
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    CURRENT BUGS SUMMARY                             │
+└────────────────────────────────────────────────────────────────────┘
+
+🔴 CRITICAL BUGS:
+1. order_id not persisted before redirect
+2. Return URL has 'token', not 'order_id'
+3. No token → order_id mapping
+4. Capture fails completely
+5. Payment left uncaptured on PayPal
+6. User sees error and can't complete signup
+
+❌ COMPLETELY BROKEN - PayPal payments don't work
+```
+
+---
+
+### 🟢 BANK TRANSFER FLOW - PAKISTAN USERS
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 1-2: SAME AS STRIPE                        │
+└────────────────────────────────────────────────────────────────────┘
+
+User signup with country=PK, plan=Starter
+    ↓
+Account created (status='pending_payment')
+    ↓
+Invoice created (currency='PKR', amount=8,499.00)
+    ↓
+Redirect to /account/plans
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 3: BANK TRANSFER FORM                      │
+└────────────────────────────────────────────────────────────────────┘
+
+/account/plans loads
+    ↓
+Shows PendingPaymentView
+    ↓
+Payment methods: [Stripe ✅, Bank Transfer ✅]  (country=PK)
+    ↓
+❌ BUG: May also show PayPal if country not passed correctly
+    ↓
+User selects Bank Transfer
+    ↓
+
+Loads bank details via GET /v1/billing/payment-configs/payment-methods/?country_code=PK&payment_method=bank_transfer
+    ↓
+Backend returns:
+    {
+        bank_name: "HBL",
+        account_title: "IGNY8 Platform",
+        account_number: "12345678",
+        iban: "PK36HABB0012345678901234",
+        swift_code: "HABBPKKA",
+        instructions: "..."
+    }
+    ↓
+Displays bank details to user
+    ↓
+User transfers PKR 8,499 to bank account
+    ↓
+User fills form:
+    - Transaction Reference: TRX123456
+    - Upload proof (receipt image)
+    - Notes: "Paid from account ending 9876"
+    ↓
+Clicks "Submit Payment Proof"
+    ↓
+
+POST /v1/billing/payments/manual/
+    └─> Body: {
+            invoice_id: <invoice_id>,
+            payment_method: 'bank_transfer',
+            amount: 8499.00,
+            manual_reference: 'TRX123456',
+            manual_notes: '...',
+            proof_url: 'https://...'
+        }
+
+BACKEND ACTIONS (billing_views.py):
+    ✅ 1. Get invoice
+    ✅ 2. Create Payment record:
+          - status = 'pending'  (awaiting admin approval)
+          - payment_method = 'bank_transfer'
+          - manual_reference = 'TRX123456'
+          - manual_proof_url = proof
+          - approved_at = None
+          - approved_by = None
+    ✅ 3. Return success
+    ❌ 4. NO email to admin
+    ❌ 5. NO email to user
+
+Frontend shows: "Payment submitted for approval"
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 4: ADMIN APPROVAL                          │
+└────────────────────────────────────────────────────────────────────┘
+
+Admin logs into Django Admin
+    ↓
+Navigates to Payments
+    ↓
+Sees Payment (status='pending', reference='TRX123456')
+    ↓
+Views proof image
+    ↓
+Verifies transaction in bank statement
+    ↓
+Changes status to 'succeeded'
+    ↓
+Sets approved_by = admin_user
+    ↓
+Clicks "Save"
+    ↓
+
+BACKEND ACTIONS (admin.py - save_model or signal):
+    ✅ 1. Mark Invoice as paid
+    ✅ 2. Update Subscription status = 'active'
+    ✅ 3. Add credits to account
+    ✅ 4. Update Account:
+          - status = 'active'
+          - payment_method = 'bank_transfer'
+    ✅ 5. Create AccountPaymentMethod:
+          - type = 'bank_transfer'
+          - is_verified = True
+          - is_default = True
+    ❌ 6. NO email to user about approval
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    PHASE 5: USER SEES ACTIVATION                    │
+└────────────────────────────────────────────────────────────────────┘
+
+User refreshes /account/plans
+    ↓
+loadBillingData() fetches updated status
+    ↓
+Shows: Active plan, credits available
+    ↓
+✅ Works correctly after admin approval
+
+
+┌────────────────────────────────────────────────────────────────────┐
+│                    CURRENT BUGS SUMMARY                             │
+└────────────────────────────────────────────────────────────────────┘
+
+🟡 MINOR BUGS:
+1. No email notification to admin
+2. No email to user on approval
+3. Currency symbol shows '$' in UI (should show 'Rs')
+4. ❌ PayPal may show for PK users if country filtering broken
+
+✅ WORKING CORRECTLY:
+1. Bank details from backend
+2. Manual payment submission
+3. Admin approval flow
+4. Account activation after approval
+```
+
+---
+
+### 💳 CREDIT PURCHASE FLOWS
+
+#### Stripe Credit Purchase (US/Global)
+
+```
+User on /account/plans (Active account)
+    ↓
+Clicks "Buy Credits"
+    ↓
+Selects package: 1000 credits for $50
+    ↓
+Clicks "Buy with Stripe"
+    ↓
+
+POST /v1/billing/stripe/purchase-credits/
+    └─> Body: {
+            credit_package_id: <package_id>,
+            payment_method: 'stripe',
+            return_url: '...',
+            cancel_url: '...'
+        }
+
+BACKEND:
+    1. Create Stripe Checkout Session (mode='payment')
+    2. metadata: { credit_package_id, credit_amount, type: 'credits' }
+    3. Return redirect_url
+
+User pays on Stripe → redirects back
+    ↓
+❌ SAME BUG: No payment verification on return
+    ↓
+Webhook fires → _add_purchased_credits()
+    ↓
+✅ Creates Invoice
+✅ Marks paid
+✅ Creates Payment
+✅ Adds credits
+    ↓
+User must manual refresh to see new credits
+```
+
+#### PayPal Credit Purchase (US/Global)
+
+```
+User clicks "Buy with PayPal"
+    ↓
+POST /v1/billing/paypal/purchase-credits/
+    ↓
+Creates PayPal Order
+    ↓
+❌ SAME BUGS: order_id not stored, token not mapped
+    ↓
+User approves on PayPal
+    ↓
+Return URL has token
+    ↓
+❌ Capture fails - no order_id
+    ↓
+Payment not completed
+```
+
+#### Bank Transfer Credit Purchase (PK)
+
+```
+User selects amount → bank transfer form
+    ↓
+Submits proof → creates Payment (pending)
+    ↓
+Admin approves → adds credits
+    ↓
+✅ Works correctly
+```
+
+---
+
+## 🔄 RECURRING PAYMENT FLOWS
+
+### Stripe Subscription Renewal
+
+```
+30 days after activation
+    ↓
+Stripe auto-charges customer
+    ↓
+Stripe sends webhook: invoice.paid
+    ↓
+
+BACKEND (_handle_invoice_paid):
+    ✅ 1. Skip if billing_reason = 'subscription_create'
+    ✅ 2. Get Subscription from stripe_subscription_id
+    ✅ 3. Add renewal credits:
+          CreditService.add_credits(account, plan.included_credits)
+    ✅ 4. Update subscription period dates
+    ❌ 5. NO email sent
+
+✅ WORKS CORRECTLY
+```
+
+### Stripe Payment Failure
+
+```
+Renewal charge fails (card declined)
+    ↓
+Stripe sends webhook: invoice.payment_failed
+    ↓
+
+BACKEND (_handle_invoice_payment_failed):
+    ✅ 1. Update Subscription status = 'past_due'
+    ✅ 2. Log failure
+    ❌ 3. TODO: Send email (not implemented)
+
+⚠️ PARTIAL - Updates status but no notification
+```
+
+### PayPal Recurring (If using PayPal Subscriptions)
+
+```
+PayPal sends: BILLING.SUBSCRIPTION.ACTIVATED
+    ↓
+BACKEND (_handle_subscription_activated):
+    ✅ Creates/updates Subscription
+    ✅ Adds credits
+    ✅ Activates account
+
+PayPal sends: BILLING.SUBSCRIPTION.PAYMENT.FAILED
+    ↓
+BACKEND (_handle_subscription_payment_failed):
+    ✅ Updates status = 'past_due'
+    ❌ TODO: Send email
+
+⚠️ PARTIAL - Works but no notifications
+```
+
+---
+
+## 🎯 ROOT CAUSES OF ALL ISSUES
+
+### 1. Country Filtering Not Applied
+**One line fix in PlansAndBillingPage.tsx:**
+```tsx
+// Line ~251 - ADD country parameter:
+const billingCountry = user?.account?.billing_country || 'US';
+const gateways = await getAvailablePaymentGateways(billingCountry);
+```
+
+### 2. No Payment Return Verification
+**Need new backend endpoints:**
+```python
+# stripe_views.py
+class VerifyStripeReturnView(APIView):
+    def get(self, request):
+        session_id = request.query_params.get('session_id')
+        # Retrieve session from Stripe
+        # Check payment status
+        # Return account/subscription status
+        
+# paypal_views.py  
+class VerifyPayPalReturnView(APIView):
+    def get(self, request):
+        token = request.query_params.get('token')
+        # Map token to order_id
+        # Check order status with PayPal
+        # Return account status
+```
+
+**Frontend needs to call these on return:**
+```tsx
+useEffect(() => {
+    const params = new URLSearchParams(location.search);
+    
+    if (params.get('success') && params.get('session_id')) {
+        verifyStripePayment(params.get('session_id'));
+    }
+    
+    if (params.get('paypal') === 'success' && params.get('token')) {
+        verifyPayPalPayment(params.get('token'));
+    }
+}, [location.search]);
+```
+
+### 3. PayPal Order ID Not Persisted
+**Fix in frontend before redirect:**
+```tsx
+// Before redirecting to PayPal:
+const { order_id, redirect_url } = await createPayPalOrder();
+localStorage.setItem('paypal_order_id', order_id);
+window.location.href = redirect_url;
+
+// On return:
+const order_id = localStorage.getItem('paypal_order_id');
+await capturePayPalOrder(order_id);
+localStorage.removeItem('paypal_order_id');
+```
+
+### 4. Currency Display Hardcoded
+**Fix dynamic currency:**
+```tsx
+const getCurrencySymbol = (country: string, method: string) => {
+    if (method === 'bank_transfer' && country === 'PK') return 'Rs';
+    return '$';
+};
+
+const getCurrencyCode = (country: string, method: string) => {
+    if (method === 'bank_transfer' && country === 'PK') return 'PKR';
+    return 'USD';
+};
+```
+
+### 5. Status Logic Inconsistent
+**Fix hasActivePlan:**
+```tsx
+const hasActivePlan = user?.account?.status === 'active' 
+                   && user?.account?.plan?.slug !== 'free'
+                   && !hasPendingInvoice;
+
+const canManageBilling = user?.account?.payment_method === 'stripe'
+                      && user?.account?.stripe_customer_id
+                      && hasActivePlan;
+```
+
+---
+
+## 📋 COMPLETE ISSUE CHECKLIST
+
+| # | Issue | Severity | Status | Fix Required |
+|---|-------|----------|--------|--------------|
+| 1 | Country not passed to payment gateway selector | 🔴 CRITICAL | Open | Add country param |
+| 2 | Stripe return doesn't verify payment | 🔴 CRITICAL | Open | Add verification endpoint |
+| 3 | PayPal order_id not persisted | 🔴 CRITICAL | Open | Store in localStorage |
+| 4 | PayPal token not mapped to order_id | 🔴 CRITICAL | Open | Backend mapping or localStorage |
+| 5 | Invoice remains pending after Stripe success | 🔴 CRITICAL | Open | Add return verification |
+| 6 | PayPal capture fails on return | 🔴 CRITICAL | Open | Fix order_id persistence |
+| 7 | Currency hardcoded to USD | 🟡 HIGH | Open | Dynamic currency by country/method |
+| 8 | Manage Billing shows for wrong users | 🟡 HIGH | Open | Check actual payment_method |
+| 9 | hasActivePlan logic incorrect | 🟡 HIGH | Open | Check account status properly |
+| 10 | No real-time status update after payment | 🟡 HIGH | Open | Polling or websocket |
+| 11 | Backend payment methods ignore country | 🟢 MEDIUM | Open | Filter by country_code |
+| 12 | No email notifications | 🟢 MEDIUM | Deferred | Add email service |
+| 13 | No webhook audit trail | 🟢 MEDIUM | Open | Store in WebhookEvent model |
+
+---
+
+## 🚀 PRIORITY FIX ORDER
+
+### IMMEDIATE (Do First):
+1. Fix country filtering in gateway selection
+2. Add Stripe return verification endpoint
+3. Fix PayPal order_id persistence
+4. Test end-to-end payment flows
+
+### HIGH PRIORITY (Do Next):
+5. Dynamic currency display
+6. Fix hasActivePlan logic
+7. Fix Manage Billing button logic
+8. Add webhook event storage
+
+### MEDIUM PRIORITY (Do After):
+9. Real-time status updates (polling/websocket)
+10. Email notifications
+11. Admin notification for manual payments
+
+---
+
+*End of Critical Issues Analysis*
+4. **Country handling simplified** - Dropdown instead of detection API
+5. **Code cleaned up** - No dead routes, no hardcoded values
+6. **All payment methods work** - Stripe, PayPal, Bank Transfer
+7. **State properly reflected** - Badges, buttons based on actual status
+
+---
+
+*Plan created based on comprehensive audit of IGNY8 payment system.*