fix(security): mandate server-side Razorpay capture verification, state machine, and eliminate unverified grants

app/payment_routes.py

@@ -117,6 +117,66 @@ async def fetch_razorpay_order_api(order_id: str, key_id: str, key_secret: str)
     return None
 
 
+async def fetch_razorpay_payment_api(payment_id: str, key_id: str, key_secret: str) -> Optional[dict]:
+    """
+    Fetch authoritative payment object from Razorpay REST API to verify final capture status.
+    Mandatory defense: HMAC signature alone only proves an attempt was initiated, NOT that funds were captured!
+    """
+    if not payment_id or not key_id or not key_secret:
+        return None
+
+    if razorpay is not None:
+        try:
+            client = razorpay.Client(auth=(key_id, key_secret))
+            return client.payment.fetch(payment_id)
+        except Exception as e:
+            logger.debug(f"[Razorpay] SDK fetch error for payment {payment_id}: {e}")
+
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as http_client:
+            resp = await http_client.get(
+                f"https://api.razorpay.com/v1/payments/{payment_id}",
+                auth=(key_id, key_secret)
+            )
+            if resp.status_code == 200:
+                return resp.json()
+            logger.warning(f"[Razorpay] REST fetch returned {resp.status_code} for payment {payment_id}: {resp.text}")
+    except Exception as e:
+        logger.error(f"[Razorpay] REST fetch exception for payment {payment_id}: {e}")
+
+    return None
+
+
+async def capture_razorpay_payment_api(payment_id: str, amount_paise: int, key_id: str, key_secret: str) -> Optional[dict]:
+    """
+    Server-authoritative payment capture for Razorpay payments in 'authorized' state.
+    """
+    if not payment_id or not key_id or not key_secret or amount_paise <= 0:
+        return None
+
+    if razorpay is not None:
+        try:
+            client = razorpay.Client(auth=(key_id, key_secret))
+            return client.payment.capture(payment_id, amount_paise)
+        except Exception as e:
+            logger.debug(f"[Razorpay] SDK capture error for payment {payment_id}: {e}")
+
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as http_client:
+            resp = await http_client.post(
+                f"https://api.razorpay.com/v1/payments/{payment_id}/capture",
+                auth=(key_id, key_secret),
+                json={"amount": amount_paise, "currency": "INR"}
+            )
+            if resp.status_code in (200, 201):
+                return resp.json()
+            logger.warning(f"[Razorpay] REST capture returned {resp.status_code} for payment {payment_id}: {resp.text}")
+    except Exception as e:
+        logger.error(f"[Razorpay] REST capture exception for payment {payment_id}: {e}")
+
+    return None
+
+
 
 
 # =========================================================
@@ -681,6 +741,16 @@ async def execute_payment_fulfillment(
             "days_remaining": days_valid,
         }
 
+    # 🔄 State Transition: Transition any pre-created order from 'created' -> 'completed'
+    if external_order_id:
+        try:
+            await transactions_collection.update_many(
+                {"transaction_id": external_order_id, "status": "created"},
+                {"$set": {"status": "completed", "fulfillment_transaction_id": transaction_id, "updated_at": now}}
+            )
+        except Exception as e:
+            logger.debug(f"[Fulfillment] Error updating order status for {external_order_id}: {e}")
+
     return fulfillment_result
 
 
@@ -963,12 +1033,32 @@ async def razorpay_create_order(
             detail=f"Razorpay order initialization failed: {str(e)}"
         )
     
+    order_id = razorpay_order.get("id")
+    now = datetime.utcnow()
+    try:
+        await transactions_collection.insert_one({
+            "transaction_id": order_id,
+            "external_order_id": order_id,
+            "user_id": user_id,
+            "amount": amount_inr,
+            "type": f"{purpose}_order",
+            "reference_id": reference_id,
+            "description": f"Razorpay Order for {purpose} ({order_id})",
+            "payment_method": "razorpay",
+            "payment_domain": "web",
+            "status": "created",
+            "metadata": metadata,
+            "created_at": now,
+        })
+    except Exception as e:
+        logger.warning(f"[RazorpayOrder] Error pre-persisting order {order_id}: {e}")
+
     return {
         "success": True,
         "domain": "web",
         "gateway": "razorpay",
         "key_id": key_id,
-        "order_id": razorpay_order["id"],
+        "order_id": order_id,
         "amount_paise": amount_paise,
         "amount": amount_inr,
         "currency": "INR",
@@ -986,7 +1076,8 @@ async def razorpay_verify_payment(
 ):
     """
     Cryptographically verify Razorpay payment HMAC SHA256 signature
-    and execute universal fulfillment for Web domain.
+    AND verify authoritative payment capture status via Razorpay REST API
+    before executing universal fulfillment.
     """
     user_id = current_user.get("uid")
     razorpay_order_id = payload.get("razorpay_order_id")
@@ -1005,7 +1096,7 @@ async def razorpay_verify_payment(
     
     key_id, key_secret = get_razorpay_credentials()
     
-    # 🔐 Verify cryptographic HMAC SHA256 signature
+    # 🔐 Step 1: Verify cryptographic HMAC SHA256 signature
     signature_data = f"{razorpay_order_id}|{razorpay_payment_id}".encode("utf-8")
     generated_signature = hmac.new(
         key_secret.encode("utf-8"),
@@ -1014,18 +1105,68 @@ async def razorpay_verify_payment(
     ).hexdigest()
     
     if not hmac.compare_digest(generated_signature, razorpay_signature):
+        await transactions_collection.update_many(
+            {"transaction_id": razorpay_order_id, "status": "created"},
+            {"$set": {"status": "failed", "error_description": "Cryptographic signature mismatch", "updated_at": datetime.utcnow()}}
+        )
         raise HTTPException(
             status_code=400,
             detail="Cryptographic payment signature mismatch. Verification failed."
         )
 
-    # 🛡️ Server-Authoritative Price & Order Verification: Never trust client-submitted amounts!
-    authoritative_amount = amount
+    # 🛡️ Step 2: Fetch and authoritatively verify payment from Razorpay REST API
+    # MANDATORY DEFENSE: HMAC signature alone only proves an attempt was initiated, NOT that funds were captured!
+    payment_info = await fetch_razorpay_payment_api(razorpay_payment_id, key_id, key_secret)
+    if not payment_info:
+        await transactions_collection.update_many(
+            {"transaction_id": razorpay_order_id, "status": "created"},
+            {"$set": {"status": "failed", "error_description": f"Payment {razorpay_payment_id} not found on Razorpay gateway", "updated_at": datetime.utcnow()}}
+        )
+        raise HTTPException(
+            status_code=400,
+            detail="Payment verification failed: Payment not found on gateway. No benefits granted."
+        )
+
+    payment_status = payment_info.get("status")
+    # If authorized and capture is pending, attempt server-side capture
+    if payment_status == "authorized":
+        order_amount_paise = payment_info.get("amount", 0)
+        captured_payment = await capture_razorpay_payment_api(razorpay_payment_id, order_amount_paise, key_id, key_secret)
+        if captured_payment:
+            payment_info = captured_payment
+            payment_status = payment_info.get("status")
+
+    if payment_status != "captured":
+        logger.warning(f"[RazorpayVerify] Payment {razorpay_payment_id} not captured. Current status: '{payment_status}'")
+        err_msg = payment_info.get("error_description") or payment_info.get("description") or f"Payment status is {payment_status}"
+        await transactions_collection.update_many(
+            {"transaction_id": razorpay_order_id, "status": "created"},
+            {"$set": {"status": "failed", "error_description": f"Gateway status '{payment_status}': {err_msg}", "updated_at": datetime.utcnow()}}
+        )
+        raise HTTPException(
+            status_code=400,
+            detail=f"Payment was not captured on gateway (status: {payment_status}). Reason: {err_msg}"
+        )
+
+    # 🛡️ Step 3: Validate payment attributes
+    payment_currency = payment_info.get("currency", "")
+    if payment_currency != "INR":
+        raise HTTPException(status_code=400, detail=f"Invalid currency '{payment_currency}'. Expected INR.")
+
+    payment_order_id = payment_info.get("order_id")
+    if payment_order_id and payment_order_id != razorpay_order_id:
+        logger.warning(f"Payment order mismatch: payment belongs to {payment_order_id}, claimed {razorpay_order_id}")
+        raise HTTPException(status_code=400, detail="Payment order mismatch. Verification failed.")
+
+    # Authoritative amount from gateway
+    payment_amount_paise = payment_info.get("amount", 0)
+    if payment_amount_paise <= 0:
+        raise HTTPException(status_code=400, detail="Authoritative payment amount must be greater than zero.")
+    authoritative_amount = float(payment_amount_paise) / 100.0
+
+    # 🛡️ Step 4: Server-Authoritative Order Verification & User Isolation
     fetched_order = await fetch_razorpay_order_api(razorpay_order_id, key_id, key_secret)
     if fetched_order:
-        order_amount_paise = fetched_order.get("amount", 0)
-        if order_amount_paise > 0:
-            authoritative_amount = float(order_amount_paise) / 100.0
         order_notes = fetched_order.get("notes") or {}
         order_user_id = order_notes.get("user_id")
         if order_user_id and str(order_user_id) != str(user_id):
@@ -1040,17 +1181,6 @@ async def razorpay_verify_payment(
             reference_id = order_notes["reference_id"]
         elif order_notes.get("plan_id"):
             reference_id = order_notes["plan_id"]
-    else:
-        # Fallback security validation when Razorpay order API is unreachable or in mock/test mode
-        if purpose == "subscription":
-            plan_id = reference_id or metadata.get("plan_id") or "sahih_pro_monthly"
-            if plan_id in CANONICAL_PLANS:
-                authoritative_amount = float(CANONICAL_PLANS[plan_id]["price"])
-        elif purpose == "business_activation":
-            authoritative_amount = 50.0
-        elif purpose == "ad_wallet":
-            if authoritative_amount < 1.0:
-                raise HTTPException(status_code=400, detail="Wallet top-up amount must be at least ₹1.")
 
     # 🛡️ Intro Offer Single-Use Guard
     if purpose == "subscription" and (reference_id == "sahih_pro_intro_5" or metadata.get("plan_id") == "sahih_pro_intro_5"):
@@ -1105,10 +1235,7 @@ async def razorpay_webhook(request: Request):
     webhook_secret = settings.razorpay.webhook_secret
 
     # 1. Cryptographic Signature Verification
-    if settings.IS_PROD and os.getenv("TEST_MODE") != "1":
-        if not webhook_secret:
-            logger.error("[RazorpayWebhook] RAZORPAY_WEBHOOK_SECRET not configured in production!")
-            raise HTTPException(status_code=500, detail="Webhook verification secret not configured")
+    if webhook_secret:
         if not signature:
             logger.warning("[RazorpayWebhook] Missing X-Razorpay-Signature header in webhook request")
             raise HTTPException(status_code=401, detail="Missing Razorpay webhook signature header")
@@ -1122,14 +1249,9 @@ async def razorpay_webhook(request: Request):
         if not hmac.compare_digest(expected_signature, signature):
             logger.warning("[RazorpayWebhook] Invalid signature received on webhook endpoint")
             raise HTTPException(status_code=401, detail="Invalid Razorpay webhook signature")
-    elif webhook_secret and signature:
-        expected_signature = hmac.new(
-            webhook_secret.encode("utf-8"),
-            raw_body,
-            hashlib.sha256
-        ).hexdigest()
-        if not hmac.compare_digest(expected_signature, signature):
-            raise HTTPException(status_code=401, detail="Invalid Razorpay webhook signature")
+    elif settings.IS_PROD:
+        logger.error("[RazorpayWebhook] RAZORPAY_WEBHOOK_SECRET not configured in production!")
+        raise HTTPException(status_code=500, detail="Webhook verification secret not configured")
 
     try:
         event_payload = json.loads(raw_body.decode("utf-8")) if raw_body else {}
@@ -2657,9 +2779,29 @@ async def create_subscription_razorpay_order(
 
     try:
         order = await create_razorpay_order_api(order_data, key_id, key_secret)
+        order_id = order.get("id")
+        now = datetime.utcnow()
+        try:
+            await transactions_collection.insert_one({
+                "transaction_id": order_id,
+                "external_order_id": order_id,
+                "user_id": user_id,
+                "amount": price_inr,
+                "type": "subscription_order",
+                "reference_id": plan_id,
+                "description": f"Subscription Order for {plan_info.get('name', plan_id)} via Razorpay ({order_id})",
+                "payment_method": "razorpay",
+                "payment_domain": "web",
+                "status": "created",
+                "metadata": {"plan_id": plan_id},
+                "created_at": now,
+            })
+        except Exception as e:
+            logger.warning(f"[SubscriptionOrder] Error pre-persisting order {order_id}: {e}")
+
         return {
             "success": True,
-            "order_id": order["id"],
+            "order_id": order_id,
             "amount": amount_paise,
             "currency": "INR",
             "key_id": key_id,
@@ -2676,7 +2818,8 @@ async def verify_subscription_razorpay(
     current_user: dict = Depends(get_current_user)
 ):
     """
-    Verifies Razorpay HMAC signature and unlocks entitlements via universal fulfillment.
+    Verifies Razorpay HMAC signature AND confirms authoritative payment capture
+    via Razorpay REST API before granting Pro entitlements.
     """
     user_id = current_user.get("uid")
     order_id = payload.get("razorpay_order_id")
@@ -2694,16 +2837,72 @@ async def verify_subscription_razorpay(
         raise HTTPException(status_code=400, detail="Missing required Razorpay payment fields")
 
     key_id, key_secret = get_razorpay_credentials()
+    
+    # 🔐 Step 1: Verify HMAC SHA256 signature
     msg = f"{order_id}|{payment_id}".encode("utf-8")
     expected_sig = hmac.new(key_secret.encode("utf-8"), msg, hashlib.sha256).hexdigest()
 
     if not hmac.compare_digest(expected_sig, signature):
+        await transactions_collection.update_many(
+            {"transaction_id": order_id, "status": "created"},
+            {"$set": {"status": "failed", "error_description": "Cryptographic signature mismatch", "updated_at": datetime.utcnow()}}
+        )
         raise HTTPException(status_code=400, detail="Invalid Razorpay signature")
 
     plan_info = CANONICAL_PLANS[plan_id]
     price = float(plan_info["price"])
+    expected_amount_paise = int(round(price * 100))
+
+    # 🛡️ Step 2: Fetch authoritative payment object directly from Razorpay REST API
+    # MANDATORY GATEWAY VERIFICATION: HMAC signature alone is NEVER proof of funds capture!
+    payment_info = await fetch_razorpay_payment_api(payment_id, key_id, key_secret)
+    if not payment_info:
+        await transactions_collection.update_many(
+            {"transaction_id": order_id, "status": "created"},
+            {"$set": {"status": "failed", "error_description": f"Payment {payment_id} not found on Razorpay gateway", "updated_at": datetime.utcnow()}}
+        )
+        raise HTTPException(
+            status_code=400,
+            detail="Payment verification failed: Payment not found on gateway. No subscription granted."
+        )
+
+    payment_status = payment_info.get("status")
+    # If authorized and capture is pending, attempt server-side capture
+    if payment_status == "authorized":
+        order_amount_paise = payment_info.get("amount", expected_amount_paise)
+        captured_payment = await capture_razorpay_payment_api(payment_id, order_amount_paise, key_id, key_secret)
+        if captured_payment:
+            payment_info = captured_payment
+            payment_status = payment_info.get("status")
+
+    if payment_status != "captured":
+        logger.warning(f"[RazorpaySubVerify] Payment {payment_id} not captured. Current status: '{payment_status}'")
+        err_msg = payment_info.get("error_description") or payment_info.get("description") or f"Payment status is {payment_status}"
+        await transactions_collection.update_many(
+            {"transaction_id": order_id, "status": "created"},
+            {"$set": {"status": "failed", "error_description": f"Gateway status '{payment_status}': {err_msg}", "updated_at": datetime.utcnow()}}
+        )
+        raise HTTPException(
+            status_code=400,
+            detail=f"Payment was not captured on gateway (status: {payment_status}). Reason: {err_msg}"
+        )
+
+    # 🛡️ Step 3: Validate payment attributes
+    payment_currency = payment_info.get("currency", "")
+    if payment_currency != "INR":
+        raise HTTPException(status_code=400, detail=f"Invalid currency '{payment_currency}'. Expected INR.")
+
+    payment_order_id = payment_info.get("order_id")
+    if payment_order_id and payment_order_id != order_id:
+        logger.warning(f"Payment order mismatch: payment belongs to {payment_order_id}, claimed {order_id}")
+        raise HTTPException(status_code=400, detail="Payment order mismatch. Verification failed.")
+
+    payment_amount_paise = payment_info.get("amount", 0)
+    if payment_amount_paise != expected_amount_paise:
+        logger.warning(f"Payment amount mismatch: expected {expected_amount_paise} paise, got {payment_amount_paise}")
+        raise HTTPException(status_code=400, detail=f"Payment amount mismatch. Expected ₹{price}, got ₹{payment_amount_paise / 100.0}")
 
-    # 🛡️ Strict single-use check for ₹5 introductory offer
+    # 🛡️ Step 4: Strict single-use check for ₹5 introductory offer
     if plan_id == "sahih_pro_intro_5":
         user_doc = await users_collection.find_one({"uid": user_id}) or {}
         existing_intro_tx = await transactions_collection.find_one({

tests/test_payment_reliability_and_razorpay_migration.py

@@ -132,9 +132,18 @@ def test_3_razorpay_signature_verification_and_wallet_credit():
         with patch("app.payment_routes.transactions_collection.find_one", new_callable=AsyncMock) as mock_tx_find, \
              patch("app.payment_routes.wallets_collection.find_one_and_update", new_callable=AsyncMock) as mock_wallet_upd, \
              patch("app.payment_routes.transactions_collection.insert_one", new_callable=AsyncMock) as mock_tx_ins, \
-             patch("app.payment_routes.fetch_razorpay_order_api", new_callable=AsyncMock) as mock_fetch_order:
+             patch("app.payment_routes.transactions_collection.update_many", new_callable=AsyncMock), \
+             patch("app.payment_routes.fetch_razorpay_order_api", new_callable=AsyncMock) as mock_fetch_order, \
+             patch("app.payment_routes.fetch_razorpay_payment_api", new_callable=AsyncMock) as mock_fetch_payment:
 
             mock_tx_find.return_value = None  # No replay
+            mock_fetch_payment.return_value = {
+                "id": payment_id,
+                "order_id": order_id,
+                "amount": 25000,
+                "currency": "INR",
+                "status": "captured",
+            }
             mock_fetch_order.return_value = {
                 "id": order_id,
                 "amount": 25000,
@@ -164,8 +173,9 @@ def test_4_tampered_signature_rejected():
             "amount": 1000.0,
         }
 
-        with pytest.raises(HTTPException) as exc_info:
-            await razorpay_verify_payment(payload=payload, current_user=mock_user)
+        with patch("app.payment_routes.transactions_collection.update_many", new_callable=AsyncMock):
+            with pytest.raises(HTTPException) as exc_info:
+                await razorpay_verify_payment(payload=payload, current_user=mock_user)
 
         assert exc_info.value.status_code == 400
         assert "mismatch" in exc_info.value.detail.lower()
@@ -200,9 +210,18 @@ def test_5_client_price_tampering_prevented():
         with patch("app.payment_routes.transactions_collection.find_one", new_callable=AsyncMock) as mock_tx_find, \
              patch("app.payment_routes.wallets_collection.find_one_and_update", new_callable=AsyncMock) as mock_wallet_upd, \
              patch("app.payment_routes.transactions_collection.insert_one", new_callable=AsyncMock), \
-             patch("app.payment_routes.fetch_razorpay_order_api", new_callable=AsyncMock) as mock_fetch_order:
+             patch("app.payment_routes.transactions_collection.update_many", new_callable=AsyncMock), \
+             patch("app.payment_routes.fetch_razorpay_order_api", new_callable=AsyncMock) as mock_fetch_order, \
+             patch("app.payment_routes.fetch_razorpay_payment_api", new_callable=AsyncMock) as mock_fetch_payment:
 
             mock_tx_find.return_value = None
+            mock_fetch_payment.return_value = {
+                "id": payment_id,
+                "order_id": order_id,
+                "amount": 10000,
+                "currency": "INR",
+                "status": "captured",
+            }
             # Authoritative Razorpay API returns 10,000 paise = ₹100.00
             mock_fetch_order.return_value = {
                 "id": order_id,
@@ -376,8 +395,18 @@ def test_10_intro_offer_single_use_enforcement_in_verification():
         }
 
         with patch("app.payment_routes.users_collection.find_one", new_callable=AsyncMock) as mock_u_find, \
-             patch("app.payment_routes.transactions_collection.find_one", new_callable=AsyncMock) as mock_tx_find:
-
+             patch("app.payment_routes.transactions_collection.find_one", new_callable=AsyncMock) as mock_tx_find, \
+             patch("app.payment_routes.transactions_collection.update_many", new_callable=AsyncMock), \
+             patch("app.payment_routes.fetch_razorpay_payment_api", new_callable=AsyncMock) as mock_fetch_payment:
+
+            # Payment exists and is captured on gateway
+            mock_fetch_payment.return_value = {
+                "id": payment_id,
+                "order_id": order_id,
+                "amount": 500,
+                "currency": "INR",
+                "status": "captured",
+            }
             # User already has has_claimed_intro_offer in document
             mock_u_find.return_value = {
                 "uid": user_id,

tests/test_payment_security_and_capture_verification.py

@@ -0,0 +1,423 @@
+"""
+Payment Security, Capture Verification & State Machine Remediation Test Suite
+=============================================================================
+Critical security audit test suite to guarantee:
+1. HMAC signature alone NEVER grants paid benefits.
+2. Uncaptured / failed / cancelled payments are strictly rejected with HTTP 400.
+3. Order pre-persistence and state transitions ('created' -> 'captured'/'failed') are enforced.
+4. Tampering with order IDs, amounts, currencies, or user accounts is blocked.
+5. Insecure webhook bypasses are eliminated.
+"""
+
+import os
+import hmac
+import hashlib
+import json
+import asyncio
+from datetime import datetime
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from fastapi import HTTPException, Request
+
+os.environ["TEST_MODE"] = "1"
+os.environ["RAZORPAY_KEY_ID"] = "rzp_test_TqgD42MZb3kwwQ"
+os.environ["RAZORPAY_KEY_SECRET"] = "EkbAfQm9ks85jHT1qErb30GJ"
+os.environ["RAZORPAY_WEBHOOK_SECRET"] = "test_webhook_secret_key_123"
+
+from app.payment_routes import (
+    razorpay_create_order,
+    razorpay_verify_payment,
+    create_subscription_razorpay_order,
+    verify_subscription_razorpay,
+    razorpay_webhook,
+    CANONICAL_PLANS,
+)
+
+
+def run_async(coro):
+    return asyncio.run(coro)
+
+
+# ==============================================================================
+# 1. WALLET TOP-UP: UNCAPTURED / FAILED / CANCELLED PAYMENT TESTS
+# ==============================================================================
+
+def test_wallet_topup_rejected_when_payment_status_is_failed():
+    """Wallet top-up MUST NOT be credited when Razorpay reports payment status == 'failed'."""
+    async def _test():
+        user_id = "user_victim_1"
+        mock_user = {"uid": user_id, "email": "victim@sahihislam.com"}
+        order_id = "order_fail_1"
+        payment_id = "pay_fail_upi_invalid"
+        key_secret = "EkbAfQm9ks85jHT1qErb30GJ"
+
+        sig = hmac.new(
+            key_secret.encode("utf-8"),
+            f"{order_id}|{payment_id}".encode("utf-8"),
+            hashlib.sha256
+        ).hexdigest()
+
+        payload = {
+            "razorpay_order_id": order_id,
+            "razorpay_payment_id": payment_id,
+            "razorpay_signature": sig,
+            "purpose": "ad_wallet",
+            "amount": 200.0,
+        }
+
+        with patch("app.payment_routes.fetch_razorpay_payment_api", new_callable=AsyncMock) as mock_fetch_payment, \
+             patch("app.payment_routes.transactions_collection.update_many", new_callable=AsyncMock) as mock_tx_upd, \
+             patch("app.payment_routes.wallets_collection.find_one_and_update", new_callable=AsyncMock) as mock_wallet_upd:
+
+            # Gateway reports status: failed (e.g. invalid UPI or bank timeout)
+            mock_fetch_payment.return_value = {
+                "id": payment_id,
+                "order_id": order_id,
+                "amount": 20000,
+                "currency": "INR",
+                "status": "failed",
+                "error_description": "Payment was declined by UPI PSP / Bank",
+            }
+
+            with pytest.raises(HTTPException) as exc_info:
+                await razorpay_verify_payment(payload=payload, current_user=mock_user)
+
+            assert exc_info.value.status_code == 400
+            assert "not captured" in exc_info.value.detail.lower()
+            # Wallet MUST NOT be touched
+            assert not mock_wallet_upd.called
+            # Order MUST be marked as failed in DB
+            assert mock_tx_upd.called
+            update_call = mock_tx_upd.call_args[0]
+            assert update_call[1]["$set"]["status"] == "failed"
+
+    run_async(_test())
+
+
+def test_wallet_topup_rejected_when_payment_status_is_created_or_cancelled():
+    """Wallet top-up MUST NOT be credited when payment was cancelled / only created."""
+    async def _test():
+        user_id = "user_cancel_1"
+        mock_user = {"uid": user_id, "email": "cancel@sahihislam.com"}
+        order_id = "order_cancel_1"
+        payment_id = "pay_cancel_modal_closed"
+        key_secret = "EkbAfQm9ks85jHT1qErb30GJ"
+
+        sig = hmac.new(
+            key_secret.encode("utf-8"),
+            f"{order_id}|{payment_id}".encode("utf-8"),
+            hashlib.sha256
+        ).hexdigest()
+
+        payload = {
+            "razorpay_order_id": order_id,
+            "razorpay_payment_id": payment_id,
+            "razorpay_signature": sig,
+            "purpose": "ad_wallet",
+            "amount": 200.0,
+        }
+
+        with patch("app.payment_routes.fetch_razorpay_payment_api", new_callable=AsyncMock) as mock_fetch_payment, \
+             patch("app.payment_routes.transactions_collection.update_many", new_callable=AsyncMock), \
+             patch("app.payment_routes.wallets_collection.find_one_and_update", new_callable=AsyncMock) as mock_wallet_upd:
+
+            # Gateway reports status: created (user closed checkout without paying)
+            mock_fetch_payment.return_value = {
+                "id": payment_id,
+                "order_id": order_id,
+                "amount": 20000,
+                "currency": "INR",
+                "status": "created",
+            }
+
+            with pytest.raises(HTTPException) as exc_info:
+                await razorpay_verify_payment(payload=payload, current_user=mock_user)
+
+            assert exc_info.value.status_code == 400
+            assert "not captured" in exc_info.value.detail.lower()
+            assert not mock_wallet_upd.called
+
+    run_async(_test())
+
+
+def test_wallet_topup_rejected_when_payment_does_not_exist_on_gateway():
+    """Rejects payment when payment ID does not exist on Razorpay."""
+    async def _test():
+        user_id = "user_notfound_1"
+        mock_user = {"uid": user_id, "email": "notfound@sahihislam.com"}
+        order_id = "order_notfound_1"
+        payment_id = "pay_forged_nonexistent"
+        key_secret = "EkbAfQm9ks85jHT1qErb30GJ"
+
+        sig = hmac.new(
+            key_secret.encode("utf-8"),
+            f"{order_id}|{payment_id}".encode("utf-8"),
+            hashlib.sha256
+        ).hexdigest()
+
+        payload = {
+            "razorpay_order_id": order_id,
+            "razorpay_payment_id": payment_id,
+            "razorpay_signature": sig,
+            "purpose": "ad_wallet",
+            "amount": 200.0,
+        }
+
+        with patch("app.payment_routes.fetch_razorpay_payment_api", new_callable=AsyncMock) as mock_fetch_payment, \
+             patch("app.payment_routes.transactions_collection.update_many", new_callable=AsyncMock):
+
+            mock_fetch_payment.return_value = None  # 404 from Razorpay
+
+            with pytest.raises(HTTPException) as exc_info:
+                await razorpay_verify_payment(payload=payload, current_user=mock_user)
+
+            assert exc_info.value.status_code == 400
+            assert "not found on gateway" in exc_info.value.detail.lower()
+
+    run_async(_test())
+
+
+# ==============================================================================
+# 2. PRO SUBSCRIPTION (₹5 INTRO OFFER): UNCAPTURED / FAILED TESTS
+# ==============================================================================
+
+def test_intro_pro_offer_rejected_when_payment_failed():
+    """₹5 Pro intro offer MUST NOT be granted when Razorpay payment status is 'failed'."""
+    async def _test():
+        user_id = "user_intro_fail"
+        mock_user = {"uid": user_id, "email": "introfail@sahihislam.com"}
+        order_id = "order_intro_1"
+        payment_id = "pay_intro_upi_error"
+        key_secret = "EkbAfQm9ks85jHT1qErb30GJ"
+
+        sig = hmac.new(
+            key_secret.encode("utf-8"),
+            f"{order_id}|{payment_id}".encode("utf-8"),
+            hashlib.sha256
+        ).hexdigest()
+
+        payload = {
+            "razorpay_order_id": order_id,
+            "razorpay_payment_id": payment_id,
+            "razorpay_signature": sig,
+            "plan_id": "sahih_pro_intro_5",
+        }
+
+        with patch("app.payment_routes.fetch_razorpay_payment_api", new_callable=AsyncMock) as mock_fetch_payment, \
+             patch("app.payment_routes.transactions_collection.update_many", new_callable=AsyncMock) as mock_tx_upd, \
+             patch("app.payment_routes.users_collection.update_one", new_callable=AsyncMock) as mock_user_upd, \
+             patch("app.payment_routes.execute_payment_fulfillment", new_callable=AsyncMock) as mock_fulfill:
+
+            mock_fetch_payment.return_value = {
+                "id": payment_id,
+                "order_id": order_id,
+                "amount": 500,
+                "currency": "INR",
+                "status": "failed",
+                "error_description": "Bank servers unavailable",
+            }
+
+            with pytest.raises(HTTPException) as exc_info:
+                await verify_subscription_razorpay(payload=payload, current_user=mock_user)
+
+            assert exc_info.value.status_code == 400
+            assert "not captured" in exc_info.value.detail.lower()
+            assert not mock_fulfill.called
+            assert not mock_user_upd.called
+            assert mock_tx_upd.called
+
+    run_async(_test())
+
+
+# ==============================================================================
+# 3. ATTRIBUTE TAMPERING: CROSS-ORDER, CROSS-USER, CURRENCY, AMOUNT
+# ==============================================================================
+
+def test_cross_order_tampering_rejected():
+    """Rejects verification when payment belongs to a different order on Razorpay."""
+    async def _test():
+        user_id = "user_cross_order"
+        mock_user = {"uid": user_id, "email": "cross@sahihislam.com"}
+        order_claimed = "order_claimed_123"
+        order_actual = "order_actual_456"
+        payment_id = "pay_captured_mismatch"
+        key_secret = "EkbAfQm9ks85jHT1qErb30GJ"
+
+        sig = hmac.new(
+            key_secret.encode("utf-8"),
+            f"{order_claimed}|{payment_id}".encode("utf-8"),
+            hashlib.sha256
+        ).hexdigest()
+
+        payload = {
+            "razorpay_order_id": order_claimed,
+            "razorpay_payment_id": payment_id,
+            "razorpay_signature": sig,
+            "plan_id": "sahih_pro_intro_5",
+        }
+
+        with patch("app.payment_routes.fetch_razorpay_payment_api", new_callable=AsyncMock) as mock_fetch_payment:
+            mock_fetch_payment.return_value = {
+                "id": payment_id,
+                "order_id": order_actual,  # MISMATCH!
+                "amount": 500,
+                "currency": "INR",
+                "status": "captured",
+            }
+
+            with pytest.raises(HTTPException) as exc_info:
+                await verify_subscription_razorpay(payload=payload, current_user=mock_user)
+
+            assert exc_info.value.status_code == 400
+            assert "order mismatch" in exc_info.value.detail.lower()
+
+    run_async(_test())
+
+
+def test_cross_user_order_hijack_rejected():
+    """Rejects verification when the order belongs to another authenticated user."""
+    async def _test():
+        caller_id = "user_attacker"
+        victim_id = "user_victim"
+        mock_user = {"uid": caller_id, "email": "attacker@sahihislam.com"}
+        order_id = "order_shared_99"
+        payment_id = "pay_captured_ok"
+        key_secret = "EkbAfQm9ks85jHT1qErb30GJ"
+
+        sig = hmac.new(
+            key_secret.encode("utf-8"),
+            f"{order_id}|{payment_id}".encode("utf-8"),
+            hashlib.sha256
+        ).hexdigest()
+
+        payload = {
+            "razorpay_order_id": order_id,
+            "razorpay_payment_id": payment_id,
+            "razorpay_signature": sig,
+            "plan_id": "sahih_pro_monthly",
+        }
+
+        with patch("app.payment_routes.fetch_razorpay_payment_api", new_callable=AsyncMock) as mock_fetch_payment, \
+             patch("app.payment_routes.fetch_razorpay_order_api", new_callable=AsyncMock) as mock_fetch_order:
+
+            mock_fetch_payment.return_value = {
+                "id": payment_id,
+                "order_id": order_id,
+                "amount": 15900,
+                "currency": "INR",
+                "status": "captured",
+            }
+            # Order belongs to victim_id!
+            mock_fetch_order.return_value = {
+                "id": order_id,
+                "amount": 15900,
+                "notes": {"user_id": victim_id, "purpose": "subscription"}
+            }
+
+            with pytest.raises(HTTPException) as exc_info:
+                await verify_subscription_razorpay(payload=payload, current_user=mock_user)
+
+            assert exc_info.value.status_code == 403
+            assert "does not belong" in exc_info.value.detail.lower()
+
+    run_async(_test())
+
+
+def test_currency_mismatch_rejected():
+    """Rejects payments captured in non-INR currency."""
+    async def _test():
+        user_id = "user_currency_test"
+        mock_user = {"uid": user_id, "email": "curr@sahihislam.com"}
+        order_id = "order_curr_1"
+        payment_id = "pay_usd_captured"
+        key_secret = "EkbAfQm9ks85jHT1qErb30GJ"
+
+        sig = hmac.new(
+            key_secret.encode("utf-8"),
+            f"{order_id}|{payment_id}".encode("utf-8"),
+            hashlib.sha256
+        ).hexdigest()
+
+        payload = {
+            "razorpay_order_id": order_id,
+            "razorpay_payment_id": payment_id,
+            "razorpay_signature": sig,
+            "plan_id": "sahih_pro_intro_5",
+        }
+
+        with patch("app.payment_routes.fetch_razorpay_payment_api", new_callable=AsyncMock) as mock_fetch_payment:
+            mock_fetch_payment.return_value = {
+                "id": payment_id,
+                "order_id": order_id,
+                "amount": 500,
+                "currency": "USD",  # INVALID CURRENCY
+                "status": "captured",
+            }
+
+            with pytest.raises(HTTPException) as exc_info:
+                await verify_subscription_razorpay(payload=payload, current_user=mock_user)
+
+            assert exc_info.value.status_code == 400
+            assert "invalid currency" in exc_info.value.detail.lower()
+
+    run_async(_test())
+
+
+# ==============================================================================
+# 4. ORDER PRE-PERSISTENCE & STATE MACHINE
+# ==============================================================================
+
+def test_order_pre_persistence_on_creation():
+    """Creating an order pre-persists the record in DB with status: 'created'."""
+    async def _test():
+        user_id = "user_order_lifecycle"
+        mock_user = {"uid": user_id, "email": "lifecycle@sahihislam.com"}
+
+        with patch("app.payment_routes.create_razorpay_order_api", new_callable=AsyncMock) as mock_create_order, \
+             patch("app.payment_routes.transactions_collection.insert_one", new_callable=AsyncMock) as mock_tx_insert:
+
+            mock_create_order.return_value = {
+                "id": "order_prepersist_123",
+                "amount": 500,
+                "currency": "INR",
+                "receipt": "rcpt_pre_1",
+            }
+
+            res = await razorpay_create_order(
+                payload={"amount": 5.0, "purpose": "subscription", "reference_id": "sahih_pro_intro_5"},
+                current_user=mock_user
+            )
+
+            assert res["success"] is True
+            assert res["order_id"] == "order_prepersist_123"
+            assert mock_tx_insert.called
+            doc = mock_tx_insert.call_args[0][0]
+            assert doc["transaction_id"] == "order_prepersist_123"
+            assert doc["status"] == "created"
+            assert doc["amount"] == 5.0
+
+    run_async(_test())
+
+
+# ==============================================================================
+# 5. WEBHOOK SIGNATURE SECURITY ENFORCEMENT
+# ==============================================================================
+
+def test_webhook_invalid_signature_rejected_in_all_modes():
+    """Webhook with forged signature is rejected with HTTP 401."""
+    async def _test():
+        payload_data = {"event": "payment.captured", "payload": {}}
+        raw_body = json.dumps(payload_data).encode("utf-8")
+
+        mock_request = AsyncMock(spec=Request)
+        mock_request.body = AsyncMock(return_value=raw_body)
+        mock_request.headers = {"X-Razorpay-Signature": "forged_invalid_signature_123"}
+
+        with pytest.raises(HTTPException) as exc_info:
+            await razorpay_webhook(request=mock_request)
+
+        assert exc_info.value.status_code == 401
+        assert "invalid razorpay webhook signature" in exc_info.value.detail.lower()
+
+    run_async(_test())