payment

app.py

@@ -12,7 +12,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
 
 from core.database import init_db
-from routers import auth, blink, credits, general, gemini
+from routers import auth, blink, credits, general, gemini, payments
 from services.drive_service import DriveService
 
 # Configure logging
@@ -87,6 +87,7 @@ app.include_router(auth.router)
 app.include_router(blink.router)
 app.include_router(gemini.router)
 app.include_router(credits.router)
+app.include_router(payments.router)
 
 
 @app.exception_handler(Exception)

core/models.py

@@ -152,3 +152,41 @@ class ApiKeyUsage(Base):
 
     def __repr__(self):
         return f"<ApiKeyUsage(index={self.key_index}, total={self.total_requests}, success={self.success_count}, failed={self.failure_count})>"
+
+
+class PaymentTransaction(Base):
+    """
+    Track payment transactions for credit purchases.
+    Supports multiple payment gateways (Razorpay now, Stripe later).
+    """
+    __tablename__ = "payment_transactions"
+
+    id = Column(Integer, primary_key=True, autoincrement=True, index=True)
+    transaction_id = Column(String(50), unique=True, index=True, nullable=False)  # Our internal ID
+    user_id = Column(String(50), index=True, nullable=False)  # Links to User.user_id
+    
+    # Order details
+    gateway = Column(String(20), nullable=False)  # razorpay, stripe
+    gateway_order_id = Column(String(100), index=True, nullable=True)  # Razorpay order_id
+    gateway_payment_id = Column(String(100), index=True, nullable=True)  # Razorpay payment_id
+    
+    # Package details
+    package_id = Column(String(50), nullable=False)  # starter, standard, pro
+    credits_amount = Column(Integer, nullable=False)  # Credits to add
+    amount_paise = Column(Integer, nullable=False)  # Amount in paise (INR * 100)
+    currency = Column(String(3), default="INR")
+    
+    # Status tracking
+    status = Column(String(20), default="created", index=True)  # created, paid, failed, refunded
+    
+    # Timestamps
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    paid_at = Column(DateTime(timezone=True), nullable=True)
+    
+    # Metadata
+    razorpay_signature = Column(String(255), nullable=True)  # For verification audit
+    error_message = Column(Text, nullable=True)
+    extra_data = Column(JSON, nullable=True)  # Additional gateway-specific data (renamed from 'metadata' - reserved)
+
+    def __repr__(self):
+        return f"<PaymentTransaction(id={self.transaction_id}, status={self.status}, amount={self.amount_paise})>"

requirements.txt

@@ -15,4 +15,5 @@ google-auth-oauthlib>=1.0.0
 google-auth-httplib2>=0.1.0
 google-genai>=1.0.0
 PyJWT>=2.8.0
+razorpay>=1.4.0
 

routers/payments.py

@@ -0,0 +1,470 @@
+"""
+Payments Router - API endpoints for credit purchases via Razorpay.
+
+Endpoints:
+- GET  /payments/packages       - List available credit packages
+- POST /payments/create-order   - Create a Razorpay order
+- POST /payments/verify         - Verify payment and add credits
+- POST /payments/webhook/razorpay - Handle Razorpay webhooks
+- GET  /payments/history        - Get user's payment history
+"""
+
+import logging
+import uuid
+from datetime import datetime
+from typing import List, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from pydantic import BaseModel
+from sqlalchemy import select, desc
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from core.database import get_db
+from core.models import User, PaymentTransaction
+from dependencies import get_current_user
+from services.razorpay_service import (
+    RazorpayService,
+    RazorpayConfigError,
+    RazorpayOrderError,
+    RazorpayVerificationError,
+    get_razorpay_service,
+    is_razorpay_configured,
+    get_package,
+    list_packages,
+    CREDIT_PACKAGES
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/payments", tags=["payments"])
+
+
+# =============================================================================
+# Request/Response Models
+# =============================================================================
+
+class PackageResponse(BaseModel):
+    """Credit package details."""
+    id: str
+    name: str
+    credits: int
+    amount_paise: int
+    amount_rupees: float
+    currency: str
+
+
+class PackagesListResponse(BaseModel):
+    """List of available packages."""
+    packages: List[PackageResponse]
+
+
+class CreateOrderRequest(BaseModel):
+    """Request to create a payment order."""
+    package_id: str
+
+
+class CreateOrderResponse(BaseModel):
+    """Response with Razorpay order details."""
+    transaction_id: str
+    razorpay_order_id: str
+    amount_paise: int
+    currency: str
+    key_id: str
+    package_id: str
+    credits: int
+
+
+class VerifyPaymentRequest(BaseModel):
+    """Request to verify a payment."""
+    razorpay_order_id: str
+    razorpay_payment_id: str
+    razorpay_signature: str
+
+
+class VerifyPaymentResponse(BaseModel):
+    """Response after payment verification."""
+    success: bool
+    message: str
+    transaction_id: str
+    credits_added: int
+    new_balance: int
+
+
+class PaymentHistoryItem(BaseModel):
+    """Single payment in history."""
+    transaction_id: str
+    package_id: str
+    credits_amount: int
+    amount_paise: int
+    currency: str
+    status: str
+    gateway: str
+    created_at: str
+    paid_at: Optional[str] = None
+
+
+class PaymentHistoryResponse(BaseModel):
+    """Payment history response."""
+    transactions: List[PaymentHistoryItem]
+    total_count: int
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+def generate_transaction_id() -> str:
+    """Generate a unique transaction ID."""
+    return f"txn_{uuid.uuid4().hex[:16]}"
+
+
+# =============================================================================
+# Endpoints
+# =============================================================================
+
+@router.get("/packages", response_model=PackagesListResponse)
+async def get_packages():
+    """
+    List all available credit packages.
+    
+    No authentication required - this is public info for pricing display.
+    """
+    packages = list_packages()
+    return PackagesListResponse(
+        packages=[PackageResponse(**pkg) for pkg in packages]
+    )
+
+
+@router.post("/create-order", response_model=CreateOrderResponse)
+async def create_order(
+    request: CreateOrderRequest,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db)
+):
+    """
+    Create a Razorpay order for credit purchase.
+    
+    The client should use the returned order_id to open
+    Razorpay checkout. After payment, call /verify endpoint.
+    """
+    # Check if Razorpay is configured
+    if not is_razorpay_configured():
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Payment service is not configured"
+        )
+    
+    # Get package
+    package = get_package(request.package_id)
+    if not package:
+        available = list(CREDIT_PACKAGES.keys())
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid package ID. Available packages: {available}"
+        )
+    
+    try:
+        # Initialize Razorpay service
+        razorpay_service = get_razorpay_service()
+        
+        # Generate our transaction ID
+        transaction_id = generate_transaction_id()
+        
+        # Create Razorpay order
+        order = razorpay_service.create_order(
+            amount_paise=package.amount_paise,
+            transaction_id=transaction_id,
+            currency=package.currency,
+            notes={
+                "user_id": user.user_id,
+                "package_id": package.id,
+                "credits": str(package.credits)
+            }
+        )
+        
+        # Save transaction to database
+        transaction = PaymentTransaction(
+            transaction_id=transaction_id,
+            user_id=user.user_id,
+            gateway="razorpay",
+            gateway_order_id=order["id"],
+            package_id=package.id,
+            credits_amount=package.credits,
+            amount_paise=package.amount_paise,
+            currency=package.currency,
+            status="created",
+            extra_data={"razorpay_order": order}
+        )
+        db.add(transaction)
+        await db.commit()
+        
+        logger.info(
+            f"Created payment order: {transaction_id} for user {user.user_id}, "
+            f"package={package.id}, amount={package.amount_paise}"
+        )
+        
+        return CreateOrderResponse(
+            transaction_id=transaction_id,
+            razorpay_order_id=order["id"],
+            amount_paise=package.amount_paise,
+            currency=package.currency,
+            key_id=razorpay_service.key_id,
+            package_id=package.id,
+            credits=package.credits
+        )
+        
+    except RazorpayConfigError as e:
+        logger.error(f"Razorpay config error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Payment service configuration error"
+        )
+    except RazorpayOrderError as e:
+        logger.error(f"Razorpay order error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to create payment order"
+        )
+
+
+@router.post("/verify", response_model=VerifyPaymentResponse)
+async def verify_payment(
+    request: VerifyPaymentRequest,
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db)
+):
+    """
+    Verify Razorpay payment and add credits.
+    
+    Called after successful Razorpay checkout.
+    Verifies the payment signature and credits the user.
+    """
+    try:
+        razorpay_service = get_razorpay_service()
+        
+        # Find the transaction
+        result = await db.execute(
+            select(PaymentTransaction).where(
+                PaymentTransaction.gateway_order_id == request.razorpay_order_id,
+                PaymentTransaction.user_id == user.user_id
+            )
+        )
+        transaction = result.scalar_one_or_none()
+        
+        if not transaction:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Transaction not found"
+            )
+        
+        # Check if already processed
+        if transaction.status == "paid":
+            return VerifyPaymentResponse(
+                success=True,
+                message="Payment already processed",
+                transaction_id=transaction.transaction_id,
+                credits_added=0,
+                new_balance=user.credits
+            )
+        
+        # Verify signature
+        is_valid = razorpay_service.verify_payment_signature(
+            order_id=request.razorpay_order_id,
+            payment_id=request.razorpay_payment_id,
+            signature=request.razorpay_signature
+        )
+        
+        if not is_valid:
+            transaction.status = "failed"
+            transaction.error_message = "Invalid payment signature"
+            await db.commit()
+            
+            logger.warning(
+                f"Invalid payment signature for transaction {transaction.transaction_id}"
+            )
+            
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Payment verification failed"
+            )
+        
+        # Update transaction
+        transaction.status = "paid"
+        transaction.gateway_payment_id = request.razorpay_payment_id
+        transaction.razorpay_signature = request.razorpay_signature
+        transaction.paid_at = datetime.utcnow()
+        
+        # Add credits to user
+        user.credits += transaction.credits_amount
+        
+        await db.commit()
+        
+        logger.info(
+            f"Payment verified: {transaction.transaction_id}, "
+            f"added {transaction.credits_amount} credits to user {user.user_id}, "
+            f"new balance: {user.credits}"
+        )
+        
+        return VerifyPaymentResponse(
+            success=True,
+            message="Payment successful! Credits added.",
+            transaction_id=transaction.transaction_id,
+            credits_added=transaction.credits_amount,
+            new_balance=user.credits
+        )
+        
+    except RazorpayVerificationError as e:
+        logger.error(f"Payment verification error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Payment verification failed"
+        )
+
+
+@router.post("/webhook/razorpay")
+async def razorpay_webhook(
+    request: Request,
+    db: AsyncSession = Depends(get_db)
+):
+    """
+    Handle Razorpay webhook events.
+    
+    This provides backup verification in case the client-side
+    verification fails (e.g., network issues after payment).
+    
+    Razorpay will retry webhooks for up to 24 hours if not acknowledged.
+    """
+    # Get signature from headers
+    signature = request.headers.get("X-Razorpay-Signature")
+    if not signature:
+        logger.warning("Webhook received without signature")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing webhook signature"
+        )
+    
+    # Get raw body for signature verification
+    body = await request.body()
+    
+    try:
+        razorpay_service = get_razorpay_service()
+        
+        # Verify webhook signature
+        if not razorpay_service.verify_webhook_signature(body, signature):
+            logger.warning("Invalid webhook signature")
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid webhook signature"
+            )
+        
+        # Parse webhook payload
+        import json
+        payload = json.loads(body)
+        event = payload.get("event")
+        
+        logger.info(f"Received Razorpay webhook: {event}")
+        
+        # Handle payment captured event
+        if event == "payment.captured":
+            payment = payload.get("payload", {}).get("payment", {}).get("entity", {})
+            order_id = payment.get("order_id")
+            payment_id = payment.get("id")
+            
+            if order_id:
+                # Find transaction
+                result = await db.execute(
+                    select(PaymentTransaction).where(
+                        PaymentTransaction.gateway_order_id == order_id
+                    )
+                )
+                transaction = result.scalar_one_or_none()
+                
+                if transaction and transaction.status != "paid":
+                    # Update transaction
+                    transaction.status = "paid"
+                    transaction.gateway_payment_id = payment_id
+                    transaction.paid_at = datetime.utcnow()
+                    
+                    # Find user and add credits
+                    user_result = await db.execute(
+                        select(User).where(User.user_id == transaction.user_id)
+                    )
+                    user = user_result.scalar_one_or_none()
+                    
+                    if user:
+                        user.credits += transaction.credits_amount
+                        logger.info(
+                            f"Webhook: Added {transaction.credits_amount} credits "
+                            f"to user {user.user_id} for transaction {transaction.transaction_id}"
+                        )
+                    
+                    await db.commit()
+        
+        # Handle payment failed event
+        elif event == "payment.failed":
+            payment = payload.get("payload", {}).get("payment", {}).get("entity", {})
+            order_id = payment.get("order_id")
+            error_reason = payment.get("error_description", "Payment failed")
+            
+            if order_id:
+                result = await db.execute(
+                    select(PaymentTransaction).where(
+                        PaymentTransaction.gateway_order_id == order_id
+                    )
+                )
+                transaction = result.scalar_one_or_none()
+                
+                if transaction and transaction.status == "created":
+                    transaction.status = "failed"
+                    transaction.error_message = error_reason
+                    await db.commit()
+                    
+                    logger.info(
+                        f"Webhook: Marked transaction {transaction.transaction_id} as failed"
+                    )
+        
+        return {"status": "ok"}
+        
+    except RazorpayConfigError:
+        logger.error("Razorpay not configured for webhook processing")
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Payment service not configured"
+        )
+
+
+@router.get("/history", response_model=PaymentHistoryResponse)
+async def get_payment_history(
+    user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db)
+):
+    """
+    Get user's payment history.
+    
+    Returns all payment transactions ordered by newest first.
+    """
+    result = await db.execute(
+        select(PaymentTransaction)
+        .where(PaymentTransaction.user_id == user.user_id)
+        .order_by(desc(PaymentTransaction.created_at))
+    )
+    transactions = result.scalars().all()
+    
+    history = []
+    for txn in transactions:
+        history.append(PaymentHistoryItem(
+            transaction_id=txn.transaction_id,
+            package_id=txn.package_id,
+            credits_amount=txn.credits_amount,
+            amount_paise=txn.amount_paise,
+            currency=txn.currency,
+            status=txn.status,
+            gateway=txn.gateway,
+            created_at=txn.created_at.isoformat() if txn.created_at else None,
+            paid_at=txn.paid_at.isoformat() if txn.paid_at else None
+        ))
+    
+    return PaymentHistoryResponse(
+        transactions=history,
+        total_count=len(history)
+    )

services/razorpay_service.py

@@ -0,0 +1,406 @@
+"""
+Razorpay Payment Service - Modular, plug-and-play payment integration.
+
+This module provides a complete Razorpay integration that can be easily
+moved to another project with minimal changes.
+
+Features:
+- Create Razorpay orders for credit purchases
+- Verify payment signatures (HMAC SHA256)
+- Process webhook events
+- Configurable credit packages
+
+Usage:
+    from services.razorpay_service import RazorpayService, CREDIT_PACKAGES
+    
+    # Initialize
+    service = RazorpayService()  # Uses environment variables
+    
+    # Or with explicit credentials
+    service = RazorpayService(
+        key_id="rzp_test_xxx",
+        key_secret="secret",
+        webhook_secret="webhook_secret"
+    )
+    
+    # Create order
+    order = service.create_order(
+        amount_paise=9900,
+        transaction_id="txn_abc123",
+        notes={"user_id": "user123"}
+    )
+    
+    # Verify payment
+    is_valid = service.verify_payment_signature(
+        order_id="order_xxx",
+        payment_id="pay_xxx",
+        signature="signature"
+    )
+
+Environment Variables:
+    RAZORPAY_KEY_ID: Your Razorpay Key ID
+    RAZORPAY_KEY_SECRET: Your Razorpay Key Secret
+    RAZORPAY_WEBHOOK_SECRET: Webhook secret for signature verification
+"""
+
+import os
+import hmac
+import hashlib
+import logging
+from typing import Optional, Dict, Any, List
+from dataclasses import dataclass
+from enum import Enum
+
+import razorpay
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Credit Packages Configuration
+# =============================================================================
+
+@dataclass
+class CreditPackage:
+    """Represents a purchasable credit package."""
+    id: str
+    name: str
+    credits: int
+    amount_paise: int  # Amount in paise (INR × 100)
+    currency: str = "INR"
+    
+    @property
+    def amount_rupees(self) -> float:
+        """Get amount in rupees."""
+        return self.amount_paise / 100
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for API responses."""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "credits": self.credits,
+            "amount_paise": self.amount_paise,
+            "amount_rupees": self.amount_rupees,
+            "currency": self.currency
+        }
+
+
+# Available credit packages
+CREDIT_PACKAGES: Dict[str, CreditPackage] = {
+    "starter": CreditPackage(
+        id="starter",
+        name="Starter Pack",
+        credits=100,
+        amount_paise=9900  # ₹99
+    ),
+    "standard": CreditPackage(
+        id="standard",
+        name="Standard Pack",
+        credits=500,
+        amount_paise=44900  # ₹449
+    ),
+    "pro": CreditPackage(
+        id="pro",
+        name="Pro Pack",
+        credits=1000,
+        amount_paise=79900  # ₹799
+    )
+}
+
+
+def get_package(package_id: str) -> Optional[CreditPackage]:
+    """Get a credit package by ID."""
+    return CREDIT_PACKAGES.get(package_id.lower())
+
+
+def list_packages() -> List[Dict[str, Any]]:
+    """List all available credit packages."""
+    return [pkg.to_dict() for pkg in CREDIT_PACKAGES.values()]
+
+
+# =============================================================================
+# Payment Status Enum
+# =============================================================================
+
+class PaymentStatus(str, Enum):
+    """Payment transaction statuses."""
+    CREATED = "created"
+    AUTHORIZED = "authorized"
+    CAPTURED = "captured"
+    PAID = "paid"
+    FAILED = "failed"
+    REFUNDED = "refunded"
+
+
+# =============================================================================
+# Razorpay Service
+# =============================================================================
+
+class RazorpayServiceError(Exception):
+    """Base exception for Razorpay service errors."""
+    pass
+
+
+class RazorpayConfigError(RazorpayServiceError):
+    """Raised when Razorpay is not properly configured."""
+    pass
+
+
+class RazorpayOrderError(RazorpayServiceError):
+    """Raised when order creation fails."""
+    pass
+
+
+class RazorpayVerificationError(RazorpayServiceError):
+    """Raised when payment verification fails."""
+    pass
+
+
+class RazorpayService:
+    """
+    Modular Razorpay payment service.
+    
+    This service handles all Razorpay interactions including:
+    - Order creation
+    - Payment signature verification
+    - Webhook signature verification
+    
+    The service can be initialized with explicit credentials or will
+    automatically use environment variables.
+    """
+    
+    def __init__(
+        self,
+        key_id: Optional[str] = None,
+        key_secret: Optional[str] = None,
+        webhook_secret: Optional[str] = None
+    ):
+        """
+        Initialize Razorpay service.
+        
+        Args:
+            key_id: Razorpay Key ID (or RAZORPAY_KEY_ID env var)
+            key_secret: Razorpay Key Secret (or RAZORPAY_KEY_SECRET env var)
+            webhook_secret: Webhook secret (or RAZORPAY_WEBHOOK_SECRET env var)
+        """
+        self.key_id = key_id or os.getenv("RAZORPAY_KEY_ID")
+        self.key_secret = key_secret or os.getenv("RAZORPAY_KEY_SECRET")
+        self.webhook_secret = webhook_secret or os.getenv("RAZORPAY_WEBHOOK_SECRET")
+        
+        if not self.key_id or not self.key_secret:
+            raise RazorpayConfigError(
+                "Razorpay credentials not configured. "
+                "Set RAZORPAY_KEY_ID and RAZORPAY_KEY_SECRET environment variables."
+            )
+        
+        # Initialize Razorpay client
+        self._client = razorpay.Client(auth=(self.key_id, self.key_secret))
+        logger.info("Razorpay service initialized")
+    
+    @property
+    def is_configured(self) -> bool:
+        """Check if the service is properly configured."""
+        return bool(self.key_id and self.key_secret)
+    
+    def create_order(
+        self,
+        amount_paise: int,
+        transaction_id: str,
+        currency: str = "INR",
+        notes: Optional[Dict[str, str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a Razorpay order for payment.
+        
+        Args:
+            amount_paise: Amount in paise (₹1 = 100 paise)
+            transaction_id: Your internal transaction/receipt ID
+            currency: Currency code (default: INR)
+            notes: Optional notes to attach to the order
+            
+        Returns:
+            Razorpay order response containing order_id
+            
+        Raises:
+            RazorpayOrderError: If order creation fails
+        """
+        try:
+            order_data = {
+                "amount": amount_paise,
+                "currency": currency,
+                "receipt": transaction_id,
+                "notes": notes or {}
+            }
+            
+            order = self._client.order.create(data=order_data)
+            
+            logger.info(
+                f"Created Razorpay order: {order['id']} "
+                f"for amount: {amount_paise} paise, "
+                f"receipt: {transaction_id}"
+            )
+            
+            return order
+            
+        except razorpay.errors.BadRequestError as e:
+            logger.error(f"Razorpay order creation failed (bad request): {e}")
+            raise RazorpayOrderError(f"Invalid order data: {e}")
+        except razorpay.errors.ServerError as e:
+            logger.error(f"Razorpay server error: {e}")
+            raise RazorpayOrderError(f"Razorpay server error: {e}")
+        except Exception as e:
+            logger.error(f"Unexpected error creating Razorpay order: {e}")
+            raise RazorpayOrderError(f"Failed to create order: {e}")
+    
+    def verify_payment_signature(
+        self,
+        order_id: str,
+        payment_id: str,
+        signature: str
+    ) -> bool:
+        """
+        Verify Razorpay payment signature.
+        
+        This MUST be called after receiving payment confirmation from the
+        client to ensure the payment is authentic.
+        
+        Args:
+            order_id: Razorpay order ID
+            payment_id: Razorpay payment ID
+            signature: Razorpay signature from checkout response
+            
+        Returns:
+            True if signature is valid
+            
+        Raises:
+            RazorpayVerificationError: If signature verification fails
+        """
+        try:
+            # Generate expected signature
+            message = f"{order_id}|{payment_id}"
+            expected_signature = hmac.new(
+                self.key_secret.encode('utf-8'),
+                message.encode('utf-8'),
+                hashlib.sha256
+            ).hexdigest()
+            
+            # Constant-time comparison to prevent timing attacks
+            is_valid = hmac.compare_digest(expected_signature, signature)
+            
+            if is_valid:
+                logger.info(f"Payment signature verified: order={order_id}, payment={payment_id}")
+            else:
+                logger.warning(f"Invalid payment signature: order={order_id}, payment={payment_id}")
+            
+            return is_valid
+            
+        except Exception as e:
+            logger.error(f"Error verifying payment signature: {e}")
+            raise RazorpayVerificationError(f"Signature verification failed: {e}")
+    
+    def verify_webhook_signature(
+        self,
+        body: bytes,
+        signature: str
+    ) -> bool:
+        """
+        Verify Razorpay webhook signature.
+        
+        Use this to authenticate incoming webhook requests.
+        
+        Args:
+            body: Raw request body bytes
+            signature: X-Razorpay-Signature header value
+            
+        Returns:
+            True if webhook signature is valid
+        """
+        if not self.webhook_secret:
+            logger.warning("Webhook secret not configured, skipping verification")
+            return False
+        
+        try:
+            expected_signature = hmac.new(
+                self.webhook_secret.encode('utf-8'),
+                body,
+                hashlib.sha256
+            ).hexdigest()
+            
+            is_valid = hmac.compare_digest(expected_signature, signature)
+            
+            if not is_valid:
+                logger.warning("Invalid webhook signature received")
+            
+            return is_valid
+            
+        except Exception as e:
+            logger.error(f"Error verifying webhook signature: {e}")
+            return False
+    
+    def fetch_payment(self, payment_id: str) -> Dict[str, Any]:
+        """
+        Fetch payment details from Razorpay.
+        
+        Args:
+            payment_id: Razorpay payment ID
+            
+        Returns:
+            Payment details from Razorpay
+        """
+        try:
+            payment = self._client.payment.fetch(payment_id)
+            return payment
+        except Exception as e:
+            logger.error(f"Error fetching payment {payment_id}: {e}")
+            raise RazorpayServiceError(f"Failed to fetch payment: {e}")
+    
+    def fetch_order(self, order_id: str) -> Dict[str, Any]:
+        """
+        Fetch order details from Razorpay.
+        
+        Args:
+            order_id: Razorpay order ID
+            
+        Returns:
+            Order details from Razorpay
+        """
+        try:
+            order = self._client.order.fetch(order_id)
+            return order
+        except Exception as e:
+            logger.error(f"Error fetching order {order_id}: {e}")
+            raise RazorpayServiceError(f"Failed to fetch order: {e}")
+
+
+# =============================================================================
+# Module-level convenience functions
+# =============================================================================
+
+_service_instance: Optional[RazorpayService] = None
+
+
+def get_razorpay_service() -> RazorpayService:
+    """
+    Get or create a singleton Razorpay service instance.
+    
+    Returns:
+        RazorpayService instance
+        
+    Raises:
+        RazorpayConfigError: If Razorpay is not configured
+    """
+    global _service_instance
+    
+    if _service_instance is None:
+        _service_instance = RazorpayService()
+    
+    return _service_instance
+
+
+def is_razorpay_configured() -> bool:
+    """Check if Razorpay credentials are configured in environment."""
+    return bool(
+        os.getenv("RAZORPAY_KEY_ID") and 
+        os.getenv("RAZORPAY_KEY_SECRET")
+    )

tests/test_razorpay.py

@@ -0,0 +1,431 @@
+"""
+Test Razorpay Payment Integration.
+
+This test file includes:
+1. Unit tests for RazorpayService (using real test API keys)
+2. Integration tests for payment endpoints
+3. End-to-end order creation flow
+
+Run with: ./venv/bin/python -m pytest tests/test_razorpay.py -v
+"""
+
+import pytest
+import os
+import sys
+import hmac
+import hashlib
+from unittest.mock import patch, MagicMock, AsyncMock
+from datetime import datetime
+
+# Add parent directory
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from dotenv import load_dotenv
+load_dotenv()
+
+from services.razorpay_service import (
+    RazorpayService,
+    RazorpayConfigError,
+    RazorpayOrderError,
+    CREDIT_PACKAGES,
+    get_package,
+    list_packages,
+    is_razorpay_configured
+)
+
+
+# =============================================================================
+# Test Credit Packages
+# =============================================================================
+
+class TestCreditPackages:
+    """Test credit package configuration."""
+    
+    def test_packages_defined(self):
+        """Verify all expected packages exist."""
+        assert "starter" in CREDIT_PACKAGES
+        assert "standard" in CREDIT_PACKAGES
+        assert "pro" in CREDIT_PACKAGES
+    
+    def test_starter_package(self):
+        """Verify starter package details."""
+        pkg = get_package("starter")
+        assert pkg is not None
+        assert pkg.credits == 100
+        assert pkg.amount_paise == 9900  # ₹99
+        assert pkg.currency == "INR"
+    
+    def test_standard_package(self):
+        """Verify standard package details."""
+        pkg = get_package("standard")
+        assert pkg is not None
+        assert pkg.credits == 500
+        assert pkg.amount_paise == 44900  # ₹449
+    
+    def test_pro_package(self):
+        """Verify pro package details."""
+        pkg = get_package("pro")
+        assert pkg is not None
+        assert pkg.credits == 1000
+        assert pkg.amount_paise == 79900  # ₹799
+    
+    def test_get_invalid_package(self):
+        """Test getting non-existent package."""
+        assert get_package("nonexistent") is None
+    
+    def test_list_packages(self):
+        """Test listing all packages."""
+        packages = list_packages()
+        assert len(packages) == 3
+        assert all("id" in p and "credits" in p and "amount_paise" in p for p in packages)
+    
+    def test_package_to_dict(self):
+        """Test package serialization."""
+        pkg = get_package("starter")
+        d = pkg.to_dict()
+        assert d["id"] == "starter"
+        assert d["credits"] == 100
+        assert d["amount_rupees"] == 99.0
+
+
+# =============================================================================
+# Test Razorpay Service Configuration
+# =============================================================================
+
+class TestRazorpayServiceConfig:
+    """Test Razorpay service configuration."""
+    
+    def test_is_configured(self):
+        """Check if Razorpay is configured (test keys should be set)."""
+        # This will pass if user has set RAZORPAY_KEY_ID and RAZORPAY_KEY_SECRET
+        result = is_razorpay_configured()
+        print(f"\n  Razorpay configured: {result}")
+        if not result:
+            pytest.skip("Razorpay not configured - set RAZORPAY_KEY_ID and RAZORPAY_KEY_SECRET")
+    
+    def test_service_initialization(self):
+        """Test service can be initialized with env vars."""
+        if not is_razorpay_configured():
+            pytest.skip("Razorpay not configured")
+        
+        service = RazorpayService()
+        assert service.is_configured
+        assert service.key_id is not None
+        assert service.key_secret is not None
+    
+    def test_service_with_invalid_credentials(self):
+        """Test service fails gracefully with no credentials."""
+        # Temporarily clear env vars
+        original_key = os.environ.pop("RAZORPAY_KEY_ID", None)
+        original_secret = os.environ.pop("RAZORPAY_KEY_SECRET", None)
+        
+        try:
+            with pytest.raises(RazorpayConfigError):
+                RazorpayService()
+        finally:
+            # Restore env vars
+            if original_key:
+                os.environ["RAZORPAY_KEY_ID"] = original_key
+            if original_secret:
+                os.environ["RAZORPAY_KEY_SECRET"] = original_secret
+
+
+# =============================================================================
+# Test Order Creation (Real API Call with Test Keys)
+# =============================================================================
+
+class TestRazorpayOrderCreation:
+    """Test order creation with real Razorpay test API."""
+    
+    @pytest.fixture
+    def razorpay_service(self):
+        """Get configured Razorpay service."""
+        if not is_razorpay_configured():
+            pytest.skip("Razorpay not configured")
+        return RazorpayService()
+    
+    def test_create_order_starter_package(self, razorpay_service):
+        """Test creating order for starter package."""
+        package = get_package("starter")
+        
+        order = razorpay_service.create_order(
+            amount_paise=package.amount_paise,
+            transaction_id=f"test_txn_{datetime.now().strftime('%Y%m%d%H%M%S')}",
+            notes={"test": "true", "package": "starter"}
+        )
+        
+        print(f"\n  Created order: {order['id']}")
+        
+        assert "id" in order
+        assert order["id"].startswith("order_")
+        assert order["amount"] == package.amount_paise
+        assert order["currency"] == "INR"
+        assert order["status"] == "created"
+    
+    def test_create_order_all_packages(self, razorpay_service):
+        """Test creating orders for all packages."""
+        for package_id, package in CREDIT_PACKAGES.items():
+            order = razorpay_service.create_order(
+                amount_paise=package.amount_paise,
+                transaction_id=f"test_{package_id}_{datetime.now().strftime('%H%M%S')}",
+                notes={"package": package_id}
+            )
+            
+            print(f"\n  {package_id}: order={order['id']}, amount=₹{order['amount']/100}")
+            
+            assert order["amount"] == package.amount_paise
+    
+    def test_fetch_order(self, razorpay_service):
+        """Test fetching order details."""
+        # First create an order
+        order = razorpay_service.create_order(
+            amount_paise=9900,
+            transaction_id=f"fetch_test_{datetime.now().strftime('%H%M%S')}"
+        )
+        
+        # Fetch it back
+        fetched = razorpay_service.fetch_order(order["id"])
+        
+        assert fetched["id"] == order["id"]
+        assert fetched["amount"] == 9900
+
+
+# =============================================================================
+# Test Signature Verification
+# =============================================================================
+
+class TestSignatureVerification:
+    """Test payment signature verification."""
+    
+    @pytest.fixture
+    def razorpay_service(self):
+        """Get configured Razorpay service."""
+        if not is_razorpay_configured():
+            pytest.skip("Razorpay not configured")
+        return RazorpayService()
+    
+    def test_verify_valid_signature(self, razorpay_service):
+        """Test verification with a valid signature."""
+        order_id = "order_test123"
+        payment_id = "pay_test456"
+        
+        # Generate valid signature
+        message = f"{order_id}|{payment_id}"
+        valid_signature = hmac.new(
+            razorpay_service.key_secret.encode('utf-8'),
+            message.encode('utf-8'),
+            hashlib.sha256
+        ).hexdigest()
+        
+        result = razorpay_service.verify_payment_signature(
+            order_id=order_id,
+            payment_id=payment_id,
+            signature=valid_signature
+        )
+        
+        assert result is True
+    
+    def test_verify_invalid_signature(self, razorpay_service):
+        """Test verification with an invalid signature."""
+        result = razorpay_service.verify_payment_signature(
+            order_id="order_test123",
+            payment_id="pay_test456",
+            signature="invalid_signature_abc123"
+        )
+        
+        assert result is False
+    
+    def test_verify_webhook_signature(self, razorpay_service):
+        """Test webhook signature verification."""
+        if not razorpay_service.webhook_secret:
+            pytest.skip("Webhook secret not configured")
+        
+        body = b'{"event":"payment.captured"}'
+        
+        # Generate valid webhook signature
+        valid_signature = hmac.new(
+            razorpay_service.webhook_secret.encode('utf-8'),
+            body,
+            hashlib.sha256
+        ).hexdigest()
+        
+        result = razorpay_service.verify_webhook_signature(body, valid_signature)
+        assert result is True
+        
+        # Test invalid signature
+        result = razorpay_service.verify_webhook_signature(body, "invalid")
+        assert result is False
+
+
+# =============================================================================
+# Test Payment Endpoints (Integration)
+# =============================================================================
+
+class TestPaymentEndpoints:
+    """Integration tests for payment API endpoints."""
+    
+    @pytest.fixture
+    def client(self):
+        """Create test client."""
+        from fastapi.testclient import TestClient
+        
+        # Set required env vars for testing
+        os.environ.setdefault("JWT_SECRET", "test-secret-key-for-jwt-testing")
+        os.environ.setdefault("GOOGLE_CLIENT_ID", "test.apps.googleusercontent.com")
+        os.environ.setdefault("RESET_DB", "true")
+        
+        with patch("services.drive_service.DriveService") as mock_drive:
+            mock_instance = MagicMock()
+            mock_instance.download_db.return_value = False
+            mock_instance.upload_db.return_value = True
+            mock_drive.return_value = mock_instance
+            
+            from app import app
+            with TestClient(app) as c:
+                yield c
+    
+    def test_get_packages_no_auth(self, client):
+        """Test packages endpoint doesn't require auth."""
+        response = client.get("/payments/packages")
+        
+        assert response.status_code == 200
+        data = response.json()
+        
+        assert "packages" in data
+        assert len(data["packages"]) == 3
+        
+        # Verify all packages present
+        package_ids = [p["id"] for p in data["packages"]]
+        assert "starter" in package_ids
+        assert "standard" in package_ids
+        assert "pro" in package_ids
+        
+        print(f"\n  Packages: {[p['id'] + '@₹' + str(p['amount_rupees']) for p in data['packages']]}")
+    
+    def test_create_order_requires_auth(self, client):
+        """Test create-order endpoint requires authentication."""
+        response = client.post(
+            "/payments/create-order",
+            json={"package_id": "starter"}
+        )
+        
+        assert response.status_code == 401
+    
+    def test_verify_requires_auth(self, client):
+        """Test verify endpoint requires authentication."""
+        response = client.post(
+            "/payments/verify",
+            json={
+                "razorpay_order_id": "order_test",
+                "razorpay_payment_id": "pay_test",
+                "razorpay_signature": "sig_test"
+            }
+        )
+        
+        assert response.status_code == 401
+    
+    def test_history_requires_auth(self, client):
+        """Test history endpoint requires authentication."""
+        response = client.get("/payments/history")
+        assert response.status_code == 401
+
+
+# =============================================================================
+# Run Standalone Test Script
+# =============================================================================
+
+def run_manual_tests():
+    """
+    Run manual tests - useful for quick verification.
+    
+    Usage: ./venv/bin/python tests/test_razorpay.py
+    """
+    print("\n" + "="*60)
+    print("RAZORPAY INTEGRATION TEST")
+    print("="*60)
+    
+    # Check configuration
+    print("\n1. Checking Razorpay configuration...")
+    if not is_razorpay_configured():
+        print("   ❌ Razorpay NOT configured!")
+        print("   Please set RAZORPAY_KEY_ID and RAZORPAY_KEY_SECRET in .env")
+        return
+    print("   ✓ Razorpay is configured")
+    
+    # Initialize service
+    print("\n2. Initializing RazorpayService...")
+    try:
+        service = RazorpayService()
+        print(f"   ✓ Service initialized")
+        print(f"   Key ID: {service.key_id[:15]}...")
+    except Exception as e:
+        print(f"   ❌ Failed: {e}")
+        return
+    
+    # List packages
+    print("\n3. Credit packages:")
+    for pkg in list_packages():
+        print(f"   • {pkg['name']}: {pkg['credits']} credits @ ₹{pkg['amount_rupees']}")
+    
+    # Create test order
+    print("\n4. Creating test order (₹99 Starter pack)...")
+    try:
+        order = service.create_order(
+            amount_paise=9900,
+            transaction_id=f"manual_test_{datetime.now().strftime('%Y%m%d_%H%M%S')}",
+            notes={"test": "manual", "source": "test_razorpay.py"}
+        )
+        print(f"   ✓ Order created!")
+        print(f"   Order ID: {order['id']}")
+        print(f"   Amount: ₹{order['amount']/100}")
+        print(f"   Status: {order['status']}")
+    except Exception as e:
+        print(f"   ❌ Failed: {e}")
+        return
+    
+    # Test signature verification
+    print("\n5. Testing signature verification...")
+    test_signature = hmac.new(
+        service.key_secret.encode(),
+        f"{order['id']}|pay_test123".encode(),
+        hashlib.sha256
+    ).hexdigest()
+    
+    valid = service.verify_payment_signature(order['id'], "pay_test123", test_signature)
+    print(f"   ✓ Valid signature: {valid}")
+    
+    invalid = service.verify_payment_signature(order['id'], "pay_test123", "wrong_sig")
+    print(f"   ✓ Invalid signature rejected: {not invalid}")
+    
+    # Test API endpoints
+    print("\n6. Testing API endpoints...")
+    from fastapi.testclient import TestClient
+    
+    os.environ.setdefault("JWT_SECRET", "test-secret")
+    os.environ.setdefault("GOOGLE_CLIENT_ID", "test.apps.googleusercontent.com")
+    os.environ.setdefault("RESET_DB", "true")
+    
+    with patch("services.drive_service.DriveService"):
+        from app import app
+        with TestClient(app) as client:
+            # Test packages endpoint
+            resp = client.get("/payments/packages")
+            print(f"   GET /payments/packages: {resp.status_code}")
+            
+            # Test auth requirement
+            resp = client.post("/payments/create-order", json={"package_id": "starter"})
+            print(f"   POST /payments/create-order (no auth): {resp.status_code} (expected 401)")
+    
+    print("\n" + "="*60)
+    print("✓ All manual tests passed!")
+    print("="*60)
+    print("\nNext steps:")
+    print("1. Start your server: ./venv/bin/uvicorn app:app --reload")
+    print("2. Login to get JWT token")
+    print("3. Call POST /payments/create-order with token")
+    print("4. Use returned order_id in Razorpay checkout")
+    print("")
+
+
+if __name__ == "__main__":
+    run_manual_tests()