Update main.py

main.py

@@ -82,31 +82,38 @@ CORS(app)
 # =============================================================================
 # PRICING CATALOGUE
 # =============================================================================
+# billing values:
+#   "subscription" — Paystack native recurring plan (starter/professional/executive)
+#   "one_time"     — single charge, lifetime access
+#   "topup"        — credit top-up purchase, no plan change
 PLANS = {
     "starter": {
         "label": "Starter",
         "price_zar": 149,
         "monthly_credits": 115,
-        "billing": "monthly",
+        "billing": "subscription",
+        "paystack_plan_code": "PLN_ryg6ylw9zpwp4r7",
     },
     "professional": {
         "label": "Professional",
         "price_zar": 399,
         "monthly_credits": 320,
-        "billing": "monthly",
+        "billing": "subscription",
+        "paystack_plan_code": "PLN_pxrcwq9fnc6lv9n",
     },
     "executive": {
         "label": "Executive",
         "price_zar": 899,
         "monthly_credits": 750,
-        "billing": "monthly",
+        "billing": "subscription",
+        "paystack_plan_code": "PLN_alp803pz8oowu8u",
     },
     "lifetime": {
         "label": "Infinite Prep (Lifetime)",
         "price_zar": 3499,
         "original_price_zar": 4999,
         "monthly_credits": 400,
-        "billing": "lifetime",
+        "billing": "one_time",
     },
     "topup_quick": {
         "label": "Quick Refill",
@@ -144,8 +151,10 @@ INSIGHT_PLANS   = {"executive", "lifetime"}
 PITCHFY_MARKER      = "plan"
 PITCHFY_MARKER_KEYS = {"plan", "createdAt"}
 
-# Plans that the cron billing sweep charges / refreshes
-BILLABLE_PLANS = {"starter", "professional", "executive", "lifetime"}
+# Recurring billing is now handled entirely by Paystack native subscriptions.
+# The cron sweep endpoint is disabled; this set is kept empty so no accidental
+# server-side charges can occur.
+BILLABLE_PLANS = set()
 
 # =============================================================================
 # FIREBASE & AI INIT
@@ -172,7 +181,7 @@ try:
     if not _gemini_key:
         raise ValueError("'Gemini' env var not set.")
     client     = genai.Client(api_key=_gemini_key)
-    MODEL_NAME = "gemini-3.1-flash-lite"
+    MODEL_NAME = "gemini-2.5-flash"
     logger.info(f"Gemini initialized ({MODEL_NAME}).")
 
     ELEVENLABS_API_KEY = os.environ.get("ELEVENLABS_API_KEY")
@@ -307,6 +316,65 @@ def _log_payment_event(uid, plan_id, payment_id, credits, event_type):
         logger.error(f"Payment event log failed for {uid}: {e}")
 
 
+def _payment_reference_exists(reference: str) -> bool:
+    """
+    Prevents the same Paystack reference from being processed twice.
+    Both the callback verification flow and the webhook can fire for the same
+    charge — this guard makes the handler idempotent.
+    """
+    if not reference:
+        return False
+    all_events = db_ref.child("payment_events").get() or {}
+    for uid_events in all_events.values():
+        if not isinstance(uid_events, dict):
+            continue
+        for event in uid_events.values():
+            if isinstance(event, dict) and str(event.get("payment_id")) == str(reference):
+                return True
+    return False
+
+
+def _find_user_by_paystack_subscription(subscription_code: str):
+    """
+    Looks up a Pitchfy user by their stored Paystack subscription code.
+    Returns (uid, user_data) or (None, None).
+    """
+    if not subscription_code:
+        return None, None
+    users = _get_pitchfy_users()
+    for uid, user_data in users.items():
+        if user_data.get("paystack_subscription_code") == subscription_code:
+            return uid, user_data
+    return None, None
+
+
+def _find_user_by_email(email: str):
+    """
+    Looks up a Pitchfy user by email address (case-insensitive).
+    Returns (uid, user_data) or (None, None).
+    """
+    if not email:
+        return None, None
+    users = _get_pitchfy_users()
+    for uid, user_data in users.items():
+        if (user_data.get("email") or "").lower() == email.lower():
+            return uid, user_data
+    return None, None
+
+
+def _find_plan_id_by_paystack_plan_code(plan_code: str):
+    """
+    Maps a Paystack plan code back to our internal plan_id.
+    Returns plan_id string or None.
+    """
+    if not plan_code:
+        return None
+    for plan_id, plan in PLANS.items():
+        if plan.get("paystack_plan_code") == plan_code:
+            return plan_id
+    return None
+
+
 # =============================================================================
 # 3. AI LOGIC FUNCTIONS
 # =============================================================================
@@ -811,7 +879,7 @@ def _collect_platform_stats() -> dict:
             price      = float(plan_cfg.get("price_zar", 0))
             billing    = plan_cfg.get("billing", "")
 
-            if event_type in ("subscription_activated", "monthly_renewal", "topup"):
+            if event_type in ("subscription_activated", "monthly_renewal", "topup", "one_time_purchase"):
                 paying_uids.add(uid)
                 total_revenue_zar        += price
                 revenue_by_plan[plan_id] += price
@@ -822,12 +890,13 @@ def _collect_platform_stats() -> dict:
 
             if event_type == "subscription_activated":
                 subscription_activations += 1
-                if billing == "lifetime":
-                    lifetime_purchases += 1
                 if prev_plan and prev_plan != plan_id:
                     upgrade_flows[f"{prev_plan}→{plan_id}"] += 1
                 prev_plan = plan_id
                 plan_history_by_uid[uid].append(plan_id)
+            elif event_type == "one_time_purchase":
+                lifetime_purchases += 1
+                plan_history_by_uid[uid].append(plan_id)
             elif event_type == "monthly_renewal":
                 renewals += 1
             elif event_type == "topup":
@@ -1009,9 +1078,6 @@ def social_signin():
     if user_data:
         if user_data.get("suspended"):
             return jsonify({"error": "Account suspended. Contact support."}), 403
-        # Back-fill Pitchfy marker keys for accounts that pre-date the plan field
-        # (e.g. SozoFix accounts signing into Pitchfy for the first time).
-        # Lightweight patch written once; subsequent logins are no-ops.
         backfill = {}
         if "plan" not in user_data:
             backfill["plan"] = "free"
@@ -1689,7 +1755,7 @@ def admin_set_plan(uid):
         if not user_data or not any(k in user_data for k in PITCHFY_MARKER_KEYS):
             return jsonify({"error": "Pitchfy user not found."}), 404
         plan_cfg = PLANS[plan_id]
-        billing  = plan_cfg.get("billing", "monthly")
+        billing  = plan_cfg.get("billing")
         update   = {
             "plan":              plan_id,
             "plan_label":        plan_cfg["label"],
@@ -1697,20 +1763,22 @@ def admin_set_plan(uid):
             "plan_activated_at": _now_iso(),
             "plan_note":         data.get("note", "Admin override"),
         }
-        if billing in ("monthly", "lifetime"):
-            update["credits"]             = plan_cfg["monthly_credits"]
+        # Grant credits for any paid plan (subscription or one-time lifetime)
+        if billing in ("subscription", "one_time"):
+            update["credits"]             = int(plan_cfg["monthly_credits"])
             update["last_credit_refresh"] = _now_iso()
-        if billing == "lifetime":
+        if billing == "one_time":
             update["is_lifetime"] = True
         user_ref.update(update)
         _log_payment_event(
             uid, plan_id, "admin_override",
-            plan_cfg.get("monthly_credits", 0), "admin_plan_set",
+            int(plan_cfg.get("monthly_credits", 0)), "admin_plan_set",
         )
         return jsonify({"success": True, "plan": plan_id, "credits": update.get("credits")}), 200
     except PermissionError as e:
         return jsonify({"error": str(e)}), 403
     except Exception as e:
+        logger.error(f"ADMIN_SET_PLAN | Failed uid={uid}: {e}\n{traceback.format_exc()}")
         return jsonify({"error": str(e)}), 500
 
 
@@ -1745,9 +1813,9 @@ def admin_refresh_credits(uid):
             return jsonify({"error": "User not found."}), 404
         plan_id = user_data.get("plan", "free")
         plan    = PLANS.get(plan_id)
-        if not plan or plan.get("billing") not in ("monthly", "lifetime"):
-            return jsonify({"error": f'Plan "{plan_id}" has no monthly refresh.'}), 400
-        credits = plan["monthly_credits"]
+        if not plan or plan.get("billing") not in ("subscription", "one_time"):
+            return jsonify({"error": f'Plan "{plan_id}" has no credit refresh.'}), 400
+        credits = int(plan["monthly_credits"])
         user_ref.update({"credits": credits, "last_credit_refresh": _now_iso()})
         return jsonify({"success": True, "credits_loaded": credits}), 200
     except PermissionError as e:
@@ -1858,155 +1926,146 @@ def admin_get_report(report_id):
 # =============================================================================
 # 15. PAYMENT WEBHOOK & BILLING (PAYSTACK)
 # =============================================================================
-
-# ---------------------------------------------------------------------------
-# charge_monthly_subscriptions
-# ---------------------------------------------------------------------------
-# Called by the /api/cron/billing-sweep endpoint.
-# Iterates only Pitchfy users on billable plans whose last_credit_refresh
-# was 30+ days ago, then either:
-#   - Refills lifetime users for free, or
-#   - Charges monthly subscribers via Paystack's charge_authorization API.
 #
-# Requires paystack_auth_code + paystack_email stored at first payment
-# (written by /api/payments/verify when billing != 'topup').
+# Architecture: Paystack native subscriptions handle all recurring billing.
+# Two complementary flows keep the DB in sync:
+#
+#   (A) CALLBACK VERIFY  — /api/payments/verify
+#       Called by the frontend immediately after Paystack redirects back.
+#       Verifies the transaction reference and activates the plan right away
+#       so the user doesn't wait for a webhook.  Idempotent via
+#       _payment_reference_exists().
+#
+#   (B) WEBHOOK          — /api/webhooks/payment
+#       Paystack-initiated events (recurring charge.success, subscription.disable).
+#       Also idempotent — handles the same reference gracefully if (A) already
+#       processed it.  Falls back to subscription_code / email lookup when
+#       metadata is absent (e.g. Paystack-triggered renewals).
+#
+# The cron billing-sweep endpoint is DISABLED — Paystack owns the recurring
+# schedule and fires webhooks; we never charge cards server-side.
 # ---------------------------------------------------------------------------
 
-def charge_monthly_subscriptions():
-    logger.info("CRON | Starting daily subscription billing sweep...")
-    # Use Pitchfy-scoped user list — never charge SozoFix-only accounts
-    users = _get_pitchfy_users()
-    now   = datetime.now(timezone.utc)
-
-    for uid, user_data in users.items():
-        plan_id = user_data.get("plan", "free")
-        if plan_id not in BILLABLE_PLANS:
-            continue
+@app.route("/api/cron/billing-sweep", methods=["POST", "GET"])
+def trigger_billing_sweep():
+    """
+    Disabled — Paystack native subscriptions handle recurring billing.
+    Kept as a tombstone endpoint so old scheduler pings get a clear response
+    rather than a 404.
+    """
+    return jsonify({
+        "success": False,
+        "message": "Billing sweep disabled. Paystack native subscriptions are active.",
+    }), 410
 
-        last_refresh_str = user_data.get("last_credit_refresh")
-        if not last_refresh_str:
-            logger.warning(f"CRON | uid={uid} plan={plan_id} has no last_credit_refresh — skipping.")
-            continue
 
-        try:
-            last_refresh_date = _parse_iso(last_refresh_str)
-        except Exception as e:
-            logger.error(f"CRON | Date parse error for uid={uid} ts='{last_refresh_str}': {e}")
-            continue
+@app.route("/api/payments/initialize", methods=["POST"])
+def initialize_payment():
+    """
+    Initialises a Paystack Checkout session and returns the hosted URL.
 
-        days_since_refresh = (now - last_refresh_date).days
-        if days_since_refresh < 30:
-            continue
+    Body: { plan_id: str, callback_url: str }
 
-        logger.info(
-            f"CRON | uid={uid} plan={plan_id} due for renewal. "
-            f"Days since last refresh: {days_since_refresh}"
-        )
+    For subscription plans the Paystack plan code is attached so Paystack
+    creates the recurring subscription automatically.
+    For one_time / topup plans, only the amount is sent.
+    """
+    uid = verify_token(request.headers.get("Authorization"))
+    if not uid:
+        return jsonify({"error": "Unauthorized."}), 401
 
-        # Lifetime: free monthly refill, no charge
-        if plan_id == "lifetime":
-            try:
-                db_ref.child(f"users/{uid}").update({
-                    "credits":             PLANS["lifetime"]["monthly_credits"],
-                    "last_credit_refresh": _now_iso(),
-                })
-                logger.info(f"CRON | Refilled lifetime credits for uid={uid}.")
-            except Exception as e:
-                logger.error(f"CRON | Firebase write failed for lifetime refill uid={uid}: {e}")
-            continue
+    data         = request.get_json() or {}
+    plan_id      = data.get("plan_id")
+    callback_url = data.get("callback_url")
 
-        # Monthly plans: charge via Paystack stored authorization
-        auth_code = user_data.get("paystack_auth_code")
-        email     = user_data.get("paystack_email")
+    if not plan_id:
+        return jsonify({"error": "plan_id is required."}), 400
+    if not callback_url:
+        return jsonify({"error": "callback_url is required."}), 400
 
-        if not auth_code or not email:
-            logger.warning(
-                f"CRON | uid={uid} plan={plan_id} needs renewal but missing "
-                f"paystack_auth_code or paystack_email — cannot charge."
-            )
-            continue
+    plan = PLANS.get(plan_id)
+    if not plan:
+        return jsonify({"error": f"Invalid plan_id '{plan_id}'."}), 400
 
-        if not PAYSTACK_SECRET_KEY:
-            logger.error("CRON | PAYSTACK_SECRET_KEY not set — cannot charge subscriptions.")
-            break
+    if not PAYSTACK_SECRET_KEY:
+        logger.error("PAYMENTS_INIT | PAYSTACK_SECRET_KEY not configured.")
+        return jsonify({"error": "Payment gateway not configured."}), 503
 
-        plan = PLANS[plan_id]
-        charge_payload = {
-            "authorization_code": auth_code,
-            "email":              email,
-            "amount":             int(plan["price_zar"] * 100),  # Paystack uses kobo
-        }
+    user_data = db_ref.child(f"users/{uid}").get() or {}
+    email     = user_data.get("email")
+    if not email:
         try:
-            res = requests.post(
-                "https://api.paystack.co/transaction/charge_authorization",
-                json=charge_payload,
-                headers={"Authorization": f"Bearer {PAYSTACK_SECRET_KEY}"},
-                timeout=15,
-            ).json()
-
-            if res.get("status") and res.get("data", {}).get("status") == "success":
-                reference = res["data"]["reference"]
-                db_ref.child(f"users/{uid}").update({
-                    "credits":             plan["monthly_credits"],
-                    "last_credit_refresh": _now_iso(),
-                })
-                _log_payment_event(uid, plan_id, reference, plan["monthly_credits"], "monthly_renewal")
-                logger.info(
-                    f"CRON | Successfully charged and renewed uid={uid} plan={plan_id} "
-                    f"reference={reference}."
-                )
-            else:
-                logger.warning(
-                    f"CRON | Charge FAILED for uid={uid} plan={plan_id}: "
-                    f"{res.get('message', 'unknown error')} | full response: {json.dumps(res)}"
-                )
-                # Optionally: flag account for follow-up
-                # db_ref.child(f"users/{uid}").update({"payment_failed": True})
+            fb_user = auth.get_user(uid)
+            email   = fb_user.email
+        except Exception:
+            email = None
+    if not email:
+        return jsonify({"error": "User email not found."}), 400
+
+    metadata = {
+        "uid":     uid,
+        "plan_id": plan_id,
+        "billing": plan.get("billing"),
+        "custom_fields": [
+            {"display_name": "Firebase UID", "variable_name": "uid",     "value": uid},
+            {"display_name": "Plan ID",      "variable_name": "plan_id", "value": plan_id},
+        ],
+    }
 
-        except requests.RequestException as e:
-            logger.error(f"CRON | Paystack API request failed for uid={uid}: {e}")
-        except Exception as e:
-            logger.error(f"CRON | Unexpected error charging uid={uid}: {e}\n{traceback.format_exc()}")
+    payload = {
+        "email":        email,
+        "callback_url": callback_url,
+        "metadata":     metadata,
+        "amount":       int(plan["price_zar"] * 100),  # always include; Paystack ignores it for plan-based charges
+    }
 
-    logger.info("CRON | Billing sweep complete.")
+    if plan.get("billing") == "subscription":
+        paystack_plan_code = plan.get("paystack_plan_code")
+        if not paystack_plan_code:
+            return jsonify({"error": f"Missing Paystack plan code for '{plan_id}'."}), 500
+        payload["plan"] = paystack_plan_code
 
+    try:
+        res = requests.post(
+            "https://api.paystack.co/transaction/initialize",
+            json=payload,
+            headers={
+                "Authorization": f"Bearer {PAYSTACK_SECRET_KEY}",
+                "Content-Type":  "application/json",
+            },
+            timeout=15,
+        ).json()
 
-@app.route("/api/cron/billing-sweep", methods=["POST", "GET"])
-def trigger_billing_sweep():
-    """
-    Triggered by an external scheduler (e.g. BetterStack monitor, cron.io).
-    Secured by WEBHOOK_SECRET in the Authorization header.
-    GET is allowed so a simple URL ping from a scheduler without a body works.
-    """
-    if not WEBHOOK_SECRET:
-        logger.error("CRON | WEBHOOK_SECRET env var not set — billing sweep endpoint is disabled.")
-        return jsonify({"error": "Cron endpoint not configured."}), 503
-
-    auth_header      = request.headers.get("Authorization", "")
-    expected_secret  = f"Bearer {WEBHOOK_SECRET}"
-    if auth_header != expected_secret:
-        logger.warning("CRON | Unauthorized attempt to trigger billing sweep.")
-        return jsonify({"error": "Unauthorized."}), 401
+        if not res.get("status"):
+            logger.warning(f"PAYMENTS_INIT | Paystack init failed: {json.dumps(res)}")
+            return jsonify({"error": res.get("message", "Could not initialize payment.")}), 400
 
-    try:
-        charge_monthly_subscriptions()
-        return jsonify({"success": True, "message": "Billing sweep completed."}), 200
+        return jsonify({
+            "success":           True,
+            "authorization_url": res["data"]["authorization_url"],
+            "access_code":       res["data"]["access_code"],
+            "reference":         res["data"]["reference"],
+        }), 200
+
+    except requests.RequestException as e:
+        logger.error(f"PAYMENTS_INIT | Paystack API failed: {e}")
+        return jsonify({"error": "Could not reach payment gateway."}), 502
     except Exception as e:
-        logger.error(f"CRON | Sweep failed: {e}\n{traceback.format_exc()}")
-        return jsonify({"error": "Internal server error during sweep."}), 500
+        logger.error(f"PAYMENTS_INIT | Unexpected error: {e}\n{traceback.format_exc()}")
+        return jsonify({"error": "Payment initialization failed."}), 500
 
 
 @app.route("/api/payments/verify", methods=["POST"])
 def verify_initial_payment():
     """
-    Called by the frontend after a successful Paystack inline payment to verify
-    the transaction and activate the plan / add credits.
+    Called by the frontend callback page after Paystack redirects back.
 
     Body: { reference: str, plan_id: str }
 
-    For subscription plans (monthly/lifetime): stores paystack_auth_code +
-    paystack_email on the user record so the cron sweep can charge recurring.
-    For topups: just adds credits, no auth code stored.
+    Verifies the Paystack transaction, then activates the correct plan type:
+      subscription — starter / professional / executive (Paystack native plan)
+      one_time     — lifetime access
+      topup        — add credits without changing plan
     """
     uid = verify_token(request.headers.get("Authorization"))
     if not uid:
@@ -2023,6 +2082,11 @@ def verify_initial_payment():
     if not plan_data:
         return jsonify({"error": f"Invalid plan_id '{plan_id}'."}), 400
 
+    # Idempotency — if the webhook already handled this reference, skip quietly
+    if _payment_reference_exists(reference):
+        logger.info(f"PAYMENTS_VERIFY | Already processed. uid={uid} reference={reference}")
+        return jsonify({"success": True, "already_processed": True}), 200
+
     if not PAYSTACK_SECRET_KEY:
         logger.error("PAYMENTS_VERIFY | PAYSTACK_SECRET_KEY not configured.")
         return jsonify({"error": "Payment gateway not configured on server."}), 503
@@ -2046,70 +2110,90 @@ def verify_initial_payment():
         )
         return jsonify({"error": "Payment verification failed."}), 400
 
-    tx_data        = res["data"]
-    auth_code      = tx_data.get("authorization", {}).get("authorization_code")
-    customer_email = tx_data.get("customer", {}).get("email")
-    billing_type   = plan_data.get("billing")
-
-    logger.info(
-        f"PAYMENTS_VERIFY | Verified OK. uid={uid} plan={plan_id} "
-        f"billing={billing_type} reference={reference}"
-    )
+    tx_data       = res["data"]
+    billing_type  = plan_data.get("billing")
+    customer      = tx_data.get("customer") or {}
+    subscription  = tx_data.get("subscription") or {}
+    authorization = tx_data.get("authorization") or {}
 
     user_ref  = db_ref.child(f"users/{uid}")
     user_data = user_ref.get() or {}
 
     try:
         if billing_type == "topup":
-            credits_to_add = plan_data["credits"]
-            new_credits    = user_data.get("credits", 0) + credits_to_add
-            user_ref.update({"credits": new_credits})
+            credits_to_add = int(plan_data["credits"])
+            new_credits    = int(user_data.get("credits", 0)) + credits_to_add
+            user_ref.update({"credits": new_credits, "last_topup_at": _now_iso()})
             _log_payment_event(uid, plan_id, reference, credits_to_add, "topup")
             logger.info(
-                f"PAYMENTS_VERIFY | TOP-UP applied: uid={uid} +{credits_to_add} credits "
-                f"(new total={new_credits})."
+                f"PAYMENTS_VERIFY | TOP-UP uid={uid} +{credits_to_add} "
+                f"new_total={new_credits}"
             )
 
-        else:
-            # monthly or lifetime
-            update = {
+        elif billing_type == "one_time":
+            credits = int(plan_data["monthly_credits"])
+            user_ref.update({
+                "plan":                plan_id,
+                "plan_label":          plan_data["label"],
+                "plan_billing":        "one_time",
+                "credits":             credits,
+                "plan_activated_at":   _now_iso(),
+                "last_credit_refresh": _now_iso(),
+                "is_lifetime":         True,
+            })
+            _log_payment_event(uid, plan_id, reference, credits, "one_time_purchase")
+            logger.info(
+                f"PAYMENTS_VERIFY | ONE-TIME uid={uid} plan={plan_id} credits={credits}"
+            )
+
+        elif billing_type == "subscription":
+            credits = int(plan_data["monthly_credits"])
+            update  = {
                 "plan":                plan_id,
                 "plan_label":          plan_data["label"],
-                "plan_billing":        billing_type,
-                "credits":             plan_data["monthly_credits"],
+                "plan_billing":        "subscription",
+                "credits":             credits,
                 "plan_activated_at":   _now_iso(),
                 "last_credit_refresh": _now_iso(),
             }
-            if auth_code:
-                update["paystack_auth_code"] = auth_code
-            if customer_email:
-                update["paystack_email"] = customer_email
-            if billing_type == "lifetime":
-                update["is_lifetime"] = True
+            # Store Paystack identifiers for webhook resolution and cancellation
+            if subscription.get("subscription_code"):
+                update["paystack_subscription_code"] = subscription["subscription_code"]
+            if subscription.get("email_token"):
+                update["paystack_email_token"]       = subscription["email_token"]
+            if customer.get("customer_code"):
+                update["paystack_customer_code"]     = customer["customer_code"]
+            if authorization.get("authorization_code"):
+                update["paystack_authorization_code"] = authorization["authorization_code"]
+            # Strip None values before writing
+            update = {k: v for k, v in update.items() if v is not None}
             user_ref.update(update)
-            _log_payment_event(
-                uid, plan_id, reference,
-                plan_data["monthly_credits"], "subscription_activated",
-            )
+            _log_payment_event(uid, plan_id, reference, credits, "subscription_activated")
             logger.info(
-                f"PAYMENTS_VERIFY | SUBSCRIPTION activated: uid={uid} plan={plan_id} "
-                f"credits={plan_data['monthly_credits']} auth_code_stored={bool(auth_code)}."
+                f"PAYMENTS_VERIFY | SUBSCRIPTION uid={uid} plan={plan_id} credits={credits} "
+                f"sub_code={subscription.get('subscription_code')}"
+            )
+
+        else:
+            logger.error(
+                f"PAYMENTS_VERIFY | Unhandled billing type '{billing_type}' plan={plan_id}"
             )
+            return jsonify({"error": f"Unhandled billing type: {billing_type}"}), 400
 
         return jsonify({"success": True}), 200
 
     except Exception as e:
         logger.critical(
-            f"PAYMENTS_VERIFY | Firebase write FAILED for uid={uid} plan={plan_id} "
+            f"PAYMENTS_VERIFY | Firebase write FAILED uid={uid} plan={plan_id} "
             f"reference={reference}: {e}\n{traceback.format_exc()}"
         )
-        return jsonify({"error": "Payment verified but account update failed. Contact support."}), 500
+        return jsonify({
+            "error": "Payment verified but account update failed. Contact support."
+        }), 500
 
 
 # ---------------------------------------------------------------------------
-# Paystack webhook (supplementary — fires for recurring charges and
-# cancellations that originate from Paystack's own subscription engine,
-# not from our cron). The two flows coexist without conflict.
+# Paystack signature verification
 # ---------------------------------------------------------------------------
 
 def _verify_paystack_signature(req):
@@ -2141,7 +2225,25 @@ def _verify_paystack_signature(req):
 
 @app.route("/api/webhooks/payment", methods=["POST"])
 def payment_webhook():
+    """
+    Receives Paystack webhook events.
+
+    Handled events:
+      charge.success      — first payment, recurring renewal, or topup charge
+      subscription.disable — user cancelled via Paystack dashboard or API
+
+    User resolution order (most → least reliable):
+      1. uid from metadata.custom_fields  (set by /api/payments/initialize)
+      2. paystack_subscription_code       (stored at first payment)
+      3. customer email                   (last resort)
+
+    Plan resolution order:
+      1. plan_id from metadata.custom_fields
+      2. Paystack plan_code → PLANS lookup
+      3. Current plan stored on the user record
+    """
     logger.info("WEBHOOK | Incoming Paystack webhook received.")
+
     try:
         _verify_paystack_signature(request)
     except PermissionError as e:
@@ -2150,212 +2252,190 @@ def payment_webhook():
 
     payload = request.get_json(silent=True)
     if not payload:
-        logger.error("WEBHOOK | Body parsed to None — Content-Type may not be application/json.")
+        logger.error("WEBHOOK | Empty or invalid JSON payload.")
         return jsonify({"error": "Empty payload."}), 400
 
     paystack_event = payload.get("event")
+    data           = payload.get("data", {}) or {}
+
     logger.info(f"WEBHOOK | Event type: '{paystack_event}'")
 
     if paystack_event not in ("charge.success", "subscription.disable"):
-        logger.info(f"WEBHOOK | Event '{paystack_event}' is not actionable — ignored.")
+        logger.info(f"WEBHOOK | Event '{paystack_event}' ignored.")
         return jsonify({"success": True, "message": "Event not actionable."}), 200
 
-    data          = payload.get("data", {})
-    payment_id    = str(data.get("reference", "unknown"))
-    channel       = data.get("channel", "unknown")
-    amount_kobo   = data.get("amount", 0)
-    metadata      = data.get("metadata", {})
-    custom_fields = metadata.get("custom_fields", [])
+    payment_id            = str(data.get("reference", "unknown"))
+    channel               = data.get("channel", "unknown")
+    metadata              = data.get("metadata", {}) or {}
+    subscription_data     = data.get("subscription") or {}
+    customer_data         = data.get("customer") or {}
+    plan_data_from_paystack = data.get("plan") or {}
 
-    logger.info(
-        f"WEBHOOK | Reference={payment_id} | Channel={channel} | "
-        f"Amount={amount_kobo} kobo | Custom fields count={len(custom_fields)}"
+    subscription_code = (
+        subscription_data.get("subscription_code")
+        if isinstance(subscription_data, dict) else None
     )
-    logger.debug(f"WEBHOOK | Full metadata: {json.dumps(metadata)}")
+    customer_email = (
+        customer_data.get("email")
+        if isinstance(customer_data, dict) else None
+    )
+    paystack_plan_code = (
+        plan_data_from_paystack.get("plan_code")
+        if isinstance(plan_data_from_paystack, dict) else None
+    )
+
+    custom_fields = metadata.get("custom_fields", []) or []
+    uid     = metadata.get("uid")
+    plan_id = metadata.get("plan_id")
 
-    uid = plan_id = None
     for f in custom_fields:
         var = f.get("variable_name")
         val = f.get("value")
-        logger.info(f"WEBHOOK | Custom field: variable_name='{var}' value='{val}'")
-        if var == "uid":
-            uid = val
-        elif var == "plan_id":
-            plan_id = val
+        if var == "uid"     and not uid:     uid     = val
+        if var == "plan_id" and not plan_id: plan_id = val
 
-    if not uid:
-        logger.error(
-            f"WEBHOOK | CRITICAL — 'uid' missing from custom_fields for payment {payment_id}. "
-            f"Raw custom_fields: {json.dumps(custom_fields)}. Plan upgrade CANNOT proceed."
-        )
-        return jsonify({"error": "Missing uid in payment metadata."}), 400
-
-    if not plan_id:
-        logger.error(
-            f"WEBHOOK | CRITICAL — 'plan_id' missing from custom_fields for payment {payment_id}, "
-            f"uid={uid}. Plan upgrade CANNOT proceed."
-        )
-        return jsonify({"error": "Missing plan_id in payment metadata."}), 400
+    user_data = None
 
-    logger.info(f"WEBHOOK | Extracted uid={uid} plan_id={plan_id} payment_id={payment_id}")
+    # Fallback resolution when metadata fields are absent (e.g. Paystack-initiated renewals)
+    if not uid and subscription_code:
+        uid, user_data = _find_user_by_paystack_subscription(subscription_code)
+    if not uid and customer_email:
+        uid, user_data = _find_user_by_email(customer_email)
+    if not plan_id and paystack_plan_code:
+        plan_id = _find_plan_id_by_paystack_plan_code(paystack_plan_code)
 
-    plan = PLANS.get(plan_id)
-    if not plan:
+    if not uid:
         logger.error(
-            f"WEBHOOK | CRITICAL — plan_id='{plan_id}' not in PLANS catalogue. "
-            f"Valid: {list(PLANS.keys())}. uid={uid} payment={payment_id}."
+            f"WEBHOOK | Could not resolve user. reference={payment_id} "
+            f"subscription_code={subscription_code} customer_email={customer_email}"
         )
-        return jsonify({"error": "Unrecognized plan."}), 400
-
-    logger.info(f"WEBHOOK | Plan resolved: {plan['label']} billing={plan['billing']}")
+        return jsonify({"error": "Could not resolve user."}), 400
 
-    logger.info(f"WEBHOOK | Fetching Firebase user record for uid={uid}")
     user_ref = db_ref.child(f"users/{uid}")
-    try:
+    if user_data is None:
         user_data = user_ref.get()
-    except Exception as e:
-        logger.critical(
-            f"WEBHOOK | Firebase read FAILED for uid={uid} payment={payment_id}: {e}\n"
-            f"{traceback.format_exc()}"
-        )
-        return jsonify({"error": "Database read error."}), 500
 
     if not user_data:
+        logger.error(f"WEBHOOK | User not found uid={uid} reference={payment_id}")
+        return jsonify({"error": "Account not found."}), 404
+
+    if not plan_id:
+        plan_id = user_data.get("plan")
+
+    plan = PLANS.get(plan_id)
+    if not plan:
         logger.error(
-            f"WEBHOOK | CRITICAL — No Firebase user record for uid={uid}. "
-            f"Payment {payment_id} for plan '{plan_id}' CANNOT be applied."
+            f"WEBHOOK | Could not resolve plan. uid={uid} plan_id={plan_id} reference={payment_id}"
         )
-        return jsonify({"error": "Account not found."}), 404
+        return jsonify({"error": "Unrecognized plan."}), 400
 
+    billing = plan.get("billing")
     logger.info(
-        f"WEBHOOK | User found: email={user_data.get('email')} "
-        f"current_plan={user_data.get('plan','free')} credits={user_data.get('credits',0)}"
+        f"WEBHOOK | Resolved uid={uid} plan_id={plan_id} billing={billing} "
+        f"reference={payment_id} channel={channel}"
     )
 
-    event = "payment_confirmed"
+    # ── subscription.disable ─────────────────────────────────────────────────
     if paystack_event == "subscription.disable":
-        event = "subscription_cancelled"
-    elif paystack_event == "charge.success" and channel == "recurring":
-        event = "monthly_renewal"
+        if user_data.get("is_lifetime", False):
+            logger.info(f"WEBHOOK | Subscription disable ignored for lifetime uid={uid}")
+            return jsonify({"success": True, "message": "Lifetime unaffected."}), 200
 
-    logger.info(f"WEBHOOK | Internal event classified as: '{event}'")
+        try:
+            user_ref.update({
+                "credits":                      0,
+                "plan":                         "free",
+                "plan_label":                   "Free",
+                "plan_billing":                 "free",
+                "plan_cancelled_at":            _now_iso(),
+                "paystack_subscription_status": "disabled",
+            })
+            _log_payment_event(uid, plan_id, payment_id, 0, "subscription_cancelled")
+            logger.info(f"WEBHOOK | Subscription cancelled uid={uid} plan={plan_id}")
+            return jsonify({"success": True}), 200
+        except Exception as e:
+            logger.critical(
+                f"WEBHOOK | Cancellation write failed uid={uid}: {e}\n{traceback.format_exc()}"
+            )
+            return jsonify({"error": "Database write error."}), 500
 
-    if event == "payment_confirmed":
-        billing = plan["billing"]
-        logger.info(f"WEBHOOK | Processing payment_confirmed. billing={billing}")
+    # ── charge.success ───────────────────────────────────────────────────────
+    if paystack_event == "charge.success":
+        # Idempotency — the callback verify may have already handled this
+        if _payment_reference_exists(payment_id):
+            logger.info(f"WEBHOOK | Reference already processed: {payment_id}")
+            return jsonify({"success": True, "already_processed": True}), 200
 
-        if billing == "topup":
-            credits        = plan["credits"]
-            credits_before = user_data.get("credits", 0)
-            credits_after  = credits_before + credits
-            logger.info(
-                f"WEBHOOK | TOP-UP: uid={uid} +{credits} credits. "
-                f"Before={credits_before} After={credits_after}"
-            )
-            try:
-                user_ref.update({"credits": credits_after})
-                logger.info(f"WEBHOOK | TOP-UP: Firebase write SUCCESS for uid={uid}")
-            except Exception as e:
-                logger.critical(
-                    f"WEBHOOK | TOP-UP: Firebase write FAILED uid={uid} payment={payment_id}: "
-                    f"{e}\n{traceback.format_exc()}"
+        try:
+            if billing == "topup":
+                credits        = int(plan["credits"])
+                credits_before = int(user_data.get("credits", 0))
+                credits_after  = credits_before + credits
+                user_ref.update({"credits": credits_after, "last_topup_at": _now_iso()})
+                _log_payment_event(uid, plan_id, payment_id, credits, "topup")
+                logger.info(
+                    f"WEBHOOK | TOP-UP uid={uid} +{credits} credits_after={credits_after}"
                 )
-                return jsonify({"error": "Database write error."}), 500
-            _log_payment_event(uid, plan_id, payment_id, credits, "topup")
-            logger.info(f"WEBHOOK | TOP-UP complete. uid={uid} payment={payment_id}")
-            return jsonify({"success": True, "credits_loaded": credits}), 200
+                return jsonify({"success": True, "credits_loaded": credits}), 200
 
-        elif billing in ("monthly", "lifetime"):
-            credits = plan["monthly_credits"]
-            update  = {
-                "credits":             credits,
-                "plan":                plan_id,
-                "plan_label":          plan["label"],
-                "plan_billing":        billing,
-                "plan_activated_at":   _now_iso(),
-                "last_credit_refresh": _now_iso(),
-            }
-            if billing == "lifetime":
-                update["is_lifetime"] = True
-            logger.info(
-                f"WEBHOOK | SUBSCRIPTION ACTIVATE: uid={uid} plan={plan_id} "
-                f"credits={credits} billing={billing}. Writing: {json.dumps(update)}"
-            )
-            try:
-                user_ref.update(update)
+            if billing == "one_time":
+                credits = int(plan["monthly_credits"])
+                user_ref.update({
+                    "credits":             credits,
+                    "plan":                plan_id,
+                    "plan_label":          plan["label"],
+                    "plan_billing":        "one_time",
+                    "plan_activated_at":   _now_iso(),
+                    "last_credit_refresh": _now_iso(),
+                    "is_lifetime":         True,
+                })
+                _log_payment_event(uid, plan_id, payment_id, credits, "one_time_purchase")
                 logger.info(
-                    f"WEBHOOK | SUBSCRIPTION ACTIVATE: Firebase write SUCCESS. "
-                    f"uid={uid} now on plan='{plan_id}' credits={credits}"
+                    f"WEBHOOK | ONE-TIME uid={uid} plan={plan_id} credits={credits}"
                 )
-            except Exception as e:
-                logger.critical(
-                    f"WEBHOOK | SUBSCRIPTION ACTIVATE: Firebase write FAILED uid={uid} "
-                    f"payment={payment_id} plan={plan_id}: {e}\n{traceback.format_exc()}"
+                return jsonify({"success": True, "credits_loaded": credits}), 200
+
+            if billing == "subscription":
+                credits = int(plan["monthly_credits"])
+                update  = {
+                    "credits":                      credits,
+                    "plan":                         plan_id,
+                    "plan_label":                   plan["label"],
+                    "plan_billing":                 "subscription",
+                    "last_credit_refresh":          _now_iso(),
+                    "paystack_subscription_status": "active",
+                }
+                if not user_data.get("plan_activated_at"):
+                    update["plan_activated_at"] = _now_iso()
+                if subscription_code:
+                    update["paystack_subscription_code"] = subscription_code
+                if isinstance(customer_data, dict) and customer_data.get("customer_code"):
+                    update["paystack_customer_code"] = customer_data["customer_code"]
+                authorization = data.get("authorization") or {}
+                if isinstance(authorization, dict) and authorization.get("authorization_code"):
+                    update["paystack_authorization_code"] = authorization["authorization_code"]
+
+                user_ref.update(update)
+                event_type = "monthly_renewal" if channel == "recurring" else "subscription_activated"
+                _log_payment_event(uid, plan_id, payment_id, credits, event_type)
+                logger.info(
+                    f"WEBHOOK | SUBSCRIPTION uid={uid} plan={plan_id} "
+                    f"event={event_type} credits={credits}"
                 )
-                return jsonify({"error": "Database write error."}), 500
-            _log_payment_event(uid, plan_id, payment_id, credits, "subscription_activated")
-            logger.info(
-                f"WEBHOOK | SUBSCRIPTION ACTIVATE complete. "
-                f"uid={uid} plan={plan_id} payment={payment_id}"
-            )
-            return jsonify({"success": True, "credits_loaded": credits}), 200
+                return jsonify({"success": True, "credits_loaded": credits}), 200
 
-        else:
             logger.error(
-                f"WEBHOOK | UNHANDLED billing type '{billing}' plan='{plan_id}' "
-                f"uid={uid} payment={payment_id}. No action taken."
+                f"WEBHOOK | Unhandled billing type '{billing}' uid={uid} plan={plan_id}"
             )
             return jsonify({"error": f"Unhandled billing type: {billing}"}), 400
 
-    elif event == "monthly_renewal":
-        current_plan_id = user_data.get("plan", plan_id)
-        current_plan    = PLANS.get(current_plan_id, plan)
-        credits         = current_plan["monthly_credits"]
-        logger.info(
-            f"WEBHOOK | MONTHLY RENEWAL: uid={uid} current_plan={current_plan_id} "
-            f"refreshing to {credits} credits."
-        )
-        try:
-            user_ref.update({"credits": credits, "last_credit_refresh": _now_iso()})
-            logger.info(f"WEBHOOK | MONTHLY RENEWAL: Firebase write SUCCESS. uid={uid}")
         except Exception as e:
             logger.critical(
-                f"WEBHOOK | MONTHLY RENEWAL: Firebase write FAILED uid={uid} "
-                f"payment={payment_id}: {e}\n{traceback.format_exc()}"
+                f"WEBHOOK | DB write failed uid={uid} plan={plan_id} "
+                f"reference={payment_id}: {e}\n{traceback.format_exc()}"
             )
             return jsonify({"error": "Database write error."}), 500
-        _log_payment_event(uid, current_plan_id, payment_id, credits, "monthly_renewal")
-        logger.info(f"WEBHOOK | MONTHLY RENEWAL complete. uid={uid} payment={payment_id}")
-        return jsonify({"success": True, "credits_loaded": credits}), 200
 
-    elif event == "subscription_cancelled":
-        if user_data.get("is_lifetime", False):
-            logger.info(f"WEBHOOK | CANCELLATION ignored — uid={uid} is lifetime.")
-            return jsonify({"success": True, "message": "Lifetime unaffected."}), 200
-        logger.info(f"WEBHOOK | CANCELLATION: uid={uid} downgrading to free.")
-        try:
-            user_ref.update({
-                "credits":           0,
-                "plan":              "free",
-                "plan_label":        "Free",
-                "plan_billing":      "free",
-                "plan_cancelled_at": _now_iso(),
-            })
-            logger.info(f"WEBHOOK | CANCELLATION: Firebase write SUCCESS. uid={uid}")
-        except Exception as e:
-            logger.critical(
-                f"WEBHOOK | CANCELLATION: Firebase write FAILED uid={uid} "
-                f"payment={payment_id}: {e}\n{traceback.format_exc()}"
-            )
-            return jsonify({"error": "Database write error."}), 500
-        _log_payment_event(uid, plan_id, payment_id, 0, event)
-        logger.info(f"WEBHOOK | CANCELLATION complete. uid={uid}")
-        return jsonify({"success": True}), 200
-
-    logger.error(
-        f"WEBHOOK | Fell through all branches. event='{event}' "
-        f"uid={uid} payment={payment_id}"
-    )
     return jsonify({"success": True}), 200