💳 Pay Wallet Backend

A secure, modular, and role-based backend API for managing digital wallet operations, including authentication, wallet management, transaction processing, and administrative control. Built with Node.js, Express.js, TypeScript, and MongoDB (Mongoose).

---

Live Url: https://pay-wallet-server2.vercel.app

🚀 Features

• Authentication & Authorization

  • JWT-based secure login system for Admin, Agent, and User
  • Password hashing using bcrypt

• Wallet Management

  • Automatic wallet creation on registration with configurable initial balance
  • Admin control to block/unblock wallets

• Transaction Operations

  • User: Add Money, Withdraw, Send Money
  • Agent: Cash-In, Cash-Out with commission tracking

• Admin Dashboard

  • View all users, agents, wallets, and transactions
  • Approve or suspend agents

• Validation & Error Handling

  • Schema validation with Zod
  • Centralized global error handler

• Role-Based Access Control (RBAC)

  • Protected routes based on user roles

• Environment-Based Configuration

  • .env file for secrets, rate limits, and system parameters

---

🧰 Tech Stack

Category	Technologies
Runtime & Framework	Node.js, Express.js, TypeScript
Database	MongoDB with Mongoose ODM
Authentication	JWT (Access + Refresh Tokens)
Security	Bcrypt, Rate Limiting, CORS
Validation	Zod
Utilities	dotenv, Morgan, http-status-codes

---

⚙️ Setup Instructions

1️⃣ Clone Repository

git clone https://github.com/abujaforhadi/Pay-Wallet-Backend.git
cd Pay-Wallet-Backend

2️⃣ Install Dependencies

npm install

3️⃣ Environment Variables

Create a .env file in the root and configure:

PORT=5000
DB_URL=your_mongodb_connection
NODE_ENV=development

JWT_ACCESS_SECRET=your_access_secret
JWT_ACCESS_EXPIRES=1d
JWT_REFRESH_SECRET=your_refresh_secret
JWT_REFRESH_EXPIRES=10d
BCRYPT_SALT_ROUNDS=10

SUPER_ADMIN_EMAIL=admin@gmail.com
SUPER_ADMIN_PASSWORD=Admin@123

TRANSACTION_FEE=
AGENT_COMMISSION=1
INITIAL_BALANCE=50

RATE_LIMIT_WINDOW_MS=
RATE_LIMIT_MAX_REQUESTS=

4️⃣ Run the Project

npm run dev

The API runs at: http://localhost:5000/api/v1

---

🧩 API Overview

Role	Key Routes
Auth	/auth/register, /auth/login
User	/user/add-money, /user/withdraw-money, /user/send-money, /user/transaction-history, /user/balance
Agent	/agent/cash-in, /agent/cash-out, /agent/commission-history, /agent/balance
Admin	/admin/users, /admin/agents, /admin/transactions, /admin/block-wallet/:id, /admin/approve-agent/:id

All routes use: Authorization: Bearer <token>

---

🧠 Highlights

• Automatic Wallet Creation: Each new user or agent gets a wallet seeded with the initial balance.
• Transaction Consistency: Wallet balance and transaction logs update atomically.
• Admin Seed: Super Admin automatically created from environment variables on startup.
• Scalable Modular Structure:

src/
├── modules/
│   ├── auth/
│   ├── user/
│   ├── agent/
│   ├── admin/
│   ├── wallet/
│   └── transaction/
├── middlewares/
├── utils/
├── config/
└── app.ts

---

🧪 Testing & Documentation

• Fully testable via Postman
• Includes all CRUD and transactional routes
• Example Postman collection (if available) can be added for reviewers

---

📄 License

This project is licensed under the ISC License.