MerchantAppOLD

MerchantAPP

ISS (Instant Settlement System) — Merchant QR Payment Collection with direct bank settlement, admin commission management, and a reporting dashboard.

Architecture

MerchantAPP/
├── backend/          # Node.js + Express + MongoDB REST API
└── merchant_app/     # Flutter mobile app (Android / iOS / Web)

Tech Stack

Layer	Technology
Backend API	Node.js 18+, Express 4, MongoDB (Mongoose)
Payment Gateway	Cashfree PG (order creation, webhooks)
Payouts	Cashfree Payout API (IMPS direct bank transfer)
Mobile App	Flutter 3.x (Dart)
State Management	Provider
Auth	JWT (access + refresh tokens)
File Uploads	Multer (KYC documents)
Logging	Winston

ISS Flow

Customer scans QR
       ↓
Cashfree payment order created
       ↓
Customer pays (UPI / Card / Net Banking)
       ↓
Cashfree webhook → payment verified
       ↓
Commission deducted (admin-configurable %)
       ↓
Net amount settled instantly to merchant bank (IMPS)
       ↓
Payout webhook confirms success / failure

Backend Setup

Prerequisites

Node.js >= 18
MongoDB (local or Atlas)
Cashfree account (PG + Payout)

Install & Run

cd backend
npm install
cp .env.example .env
# Fill in .env with your credentials
npm run dev

Seed Admin User (first time only)

curl -X POST http://localhost:5000/api/admin/seed

Environment Variables

Variable	Description
`PORT`	Server port (default 5000)
`MONGODB_URI`	MongoDB connection string
`JWT_SECRET`	JWT signing secret (min 32 chars)
`JWT_REFRESH_SECRET`	Refresh token secret
`CASHFREE_APP_ID`	Cashfree PG App ID
`CASHFREE_SECRET_KEY`	Cashfree PG Secret Key
`CASHFREE_BASE_URL`	`https://sandbox.cashfree.com/pg` (test) or `https://api.cashfree.com/pg` (prod)
`CASHFREE_PAYOUT_CLIENT_ID`	Cashfree Payout Client ID
`CASHFREE_PAYOUT_CLIENT_SECRET`	Cashfree Payout Client Secret
`CASHFREE_PAYOUT_BASE_URL`	`https://payout-gamma.cashfree.com` (test)
`CASHFREE_WEBHOOK_SECRET`	Webhook signature secret
`APP_BASE_URL`	Public URL of this backend (used in QR payment URLs)
`FRONTEND_URL`	Flutter web / frontend URL (for CORS & redirects)
`DEFAULT_COMMISSION_RATE`	Default commission % (e.g. `2.0`)
`MIN_SETTLEMENT_AMOUNT`	Min amount before settlement triggers (e.g. `100`)

API Endpoints

POST   /api/auth/register
POST   /api/auth/login
POST   /api/auth/logout
GET    /api/auth/me
PUT    /api/auth/change-password

GET    /api/merchant/dashboard
GET    /api/merchant/profile
PUT    /api/merchant/profile
POST   /api/merchant/kyc
GET    /api/merchant/kyc
POST   /api/merchant/bank-details
GET    /api/merchant/bank-details

GET    /api/qr
POST   /api/qr/static
POST   /api/qr/dynamic
GET    /api/qr/scan/:qrId         (public)
GET    /api/qr/:qrId/image
PATCH  /api/qr/:qrId/deactivate
DELETE /api/qr/:qrId

POST   /api/payment/create-order  (public)
GET    /api/payment/verify        (public)
POST   /api/payment/webhook       (Cashfree PG webhook)
GET    /api/payment/return        (Cashfree redirect)
GET    /api/payment/transactions
GET    /api/payment/transactions/:orderId

GET    /api/settlement
GET    /api/settlement/:settlementRef
POST   /api/settlement/payout-webhook (Cashfree Payout webhook)

GET    /api/reports/transactions
GET    /api/reports/settlements

GET    /api/admin/dashboard
GET    /api/admin/merchants
GET    /api/admin/merchants/:merchantId
PATCH  /api/admin/merchants/:merchantId/status
PATCH  /api/admin/merchants/:merchantId/kyc
POST   /api/admin/merchants/:merchantId/settle
GET    /api/admin/transactions
GET    /api/admin/settlements
POST   /api/admin/commission/global
POST   /api/admin/commission/merchant/:merchantId
DELETE /api/admin/commission/merchant/:merchantId
GET    /api/admin/reports/transactions
GET    /api/admin/reports/commissions
GET    /api/admin/reports/settlements

Flutter App Setup

cd merchant_app
flutter pub get
flutter run            # Android / iOS
flutter build web      # Web build for Hostinger

Update API URL

Edit lib/core/constants/app_constants.dart:

// Android emulator
static const String baseUrl = 'http://10.0.2.2:5000/api';

// Physical device / production
static const String baseUrl = 'https://merchantapp-production.up.railway.app/api';

Deployment

Backend → Render (Free)

Push this repo to GitHub
Go to render.com → New Web Service → Connect GitHub repo
Set Root Directory = backend, Start Command = node src/server.js
Add all environment variables from backend/.env.example
Add MongoDB Atlas free cluster connection string as MONGODB_URI
Render auto-deploys on every push to main

Frontend → Hostinger

Run flutter build web --release --base-href "/" inside merchant_app/
Upload contents of merchant_app/build/web/ to Hostinger public_html/ via File Manager or FTP
.htaccess is already included — handles SPA routing + HTTPS + caching
Set index.html as the default document in hPanel

See DEPLOYMENT.md for complete step-by-step guide.

License

MIT # MerchantAppOLD # MerchantAppOLD