💳 Payment_Wallet_Page: IoT Billing & Wallet Management Hub

🌟 Project Summary

This monorepo contains the complete, full-stack application logic necessary for the Payment Wallet system within the broader Bicycle Stand Locker IoT platform. It is the financial backbone that enables secure top-ups and facilitates automated, usage-based billing driven by real-time data from the physical IoT locker devices.

---

📌 Project Overview

A full-stack web application designed to handle digital wallet recharges, automated ride fare deductions, and secure transaction tracking for a bicycle rental ecosystem.

Built using React + Node.js, the system integrates Razorpay APIs to enable secure, verifiable payments with backend-level signature validation.

---

💡 Core Features

• Razorpay Integration: Secure handling of user top-ups via Razorpay's payment gateway (supporting multiple channels).
• Automated Post-Ride Deduction (IoT Billing): Implements a precise billing mechanism where final usage fees are instantly and automatically deducted from the user's wallet balance upon receiving the ride-end data from the IoT device.
• Real-Time Balance: Manages and displays the user's current account balance for immediate oversight.
• Transaction Transparency: Provides a detailed, auditable ledger of all wallet top-ups and final ride deductions.

---

🚀 Core Functionalities

🔐 Secure Wallet Recharge (Razorpay Integration)

• Backend generates Razorpay Order IDs securely
• Frontend handles checkout via Razorpay Checkout.js
• Backend verifies payments using HMAC SHA256 cryptographic signature validation
• Prevents tampering and ensures end-to-end payment integrity

⚙️ Auto-Debit Fare Engine

• Automatically calculates ride fare post-trip
• Deducts wallet balance without manual intervention
• Ensures real-time wallet consistency

📜 Transaction Ledger System

• Maintains persistent, chronological transaction history
• Tracks:
  • Credits (wallet recharges)
  • Debits (ride fares)
• Stored using MongoDB with Mongoose schema validation

📊 Real-Time Dashboard

• Built using React + Tailwind CSS + Shadcn UI
• Displays:
  • Current wallet balance
  • Transaction history
• Fully responsive and optimized for real-time updates

---

🛠️ Tech Stack

🎨 Frontend

Technology	Purpose
React (Vite)	UI framework & build tool
Tailwind CSS	Utility-first styling
Radix UI / Shadcn UI	Accessible component library
Razorpay Checkout.js	Payment gateway integration
Lucide React	Icon library

⚙️ Backend

Technology	Purpose
Node.js & Express.js	Server framework
MongoDB & Mongoose	Database & schema validation
Razorpay Node SDK	Payment order creation
Crypto (HMAC SHA256)	Signature verification

---

📂 Project Structure

bicycle-wallet-system/
├── bicycle-backend/          # Node.js/Express API server
│   ├── config/               # Razorpay configuration
│   ├── controllers/          # Recharge, verification, auto-debit logic
│   ├── models/               # Wallet & transaction schemas
│   ├── routes/               # API endpoints
│   └── server.js             # Entry point
└── bicycle-frontend/         # React/Vite client
    ├── src/
    │   ├── components/ui/    # Reusable UI components
    │   ├── App.jsx           # Dashboard & state logic
    │   └── main.jsx          # Entry point
    └── package.json

---

⚙️ Installation & Setup

🔧 Prerequisites

• Node.js installed
• MongoDB (local or Atlas)
• Razorpay Developer Account (Test Keys)

1️⃣ Backend Setup

cd bicycle-backend
npm install

Create a .env file:

PORT=5000
MONGODB_URI=mongodb://localhost:27017/bicycle_wallet
RAZORPAY_KEY_ID=your_key
RAZORPAY_KEY_SECRET=your_secret

Run the server:

npm run dev

Server runs on: http://localhost:5000

2️⃣ Frontend Setup

cd bicycle-frontend
npm install
npm run dev

App runs on: http://localhost:5173

---

📡 API Endpoints

Wallet Management — /api/wallet

Method	Endpoint	Description
GET	/api/wallet/:userId	Fetch wallet balance
POST	/api/wallet/auto-debit	Deduct ride fare

Payments — /api/payment

Method	Endpoint	Description
POST	/api/payment/create-order	Generate Razorpay order
POST	/api/payment/verify-payment	Verify payment signature

---

💡 Usage Flow

1. Dashboard     →  User views current wallet balance
2. Recharge      →  User selects amount
                 →  Frontend requests Razorpay Order ID from backend
                 →  Razorpay Checkout modal opens
3. Verification  →  Razorpay returns payment signature
                 →  Backend verifies using HMAC SHA256
4. Credit Wallet →  Balance updated in database
                 →  Transaction logged in ledger

---

🔒 Security Highlights

• HMAC SHA256 signature verification prevents payment tampering
• Backend-controlled order creation ensures a secure payment lifecycle
• Data integrity maintained via validated MongoDB schemas

---

📈 System Design Highlights

• Separation of payment verification logic and wallet management
• Scalable backend architecture using Express modular routing
• Persistent ledger system for auditability and traceability

---

🔮 Future Enhancements

• JWT-based authentication system
• Razorpay Webhooks for async payment handling
• Automated PDF invoice generation
• Multi-user support with role-based access control

---

📄 License

This project is open-source and available under the MIT License.