Skip to content

Grace-CODE-D/StellarEduPay

ย 
ย 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

180 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

StellarEduPay

A decentralized school fee payment system built on the Stellar blockchain network. StellarEduPay enables transparent, immutable, and verifiable school fee payments โ€” eliminating manual reconciliation, reducing fraud, and providing instant proof of payment for both schools and parents.

License: MIT


๐Ÿ“‹ Table of Contents


๐ŸŽฏ Problem Statement

Traditional school fee payment systems face several challenges:

  • Manual Reconciliation: Schools spend hours matching bank deposits to student records
  • Lack of Transparency: Parents have no immediate proof of payment
  • Fraud Risk: Paper receipts can be forged or lost
  • Delayed Confirmation: Bank transfers take days to confirm
  • High Transaction Fees: Traditional payment processors charge significant fees
  • Poor Audit Trail: Difficult to track payment history and generate reports

๐Ÿ’ก Solution Overview

StellarEduPay leverages the Stellar blockchain network to solve these problems:

  1. Instant Verification: Payments are confirmed on the blockchain within 3-5 seconds
  2. Immutable Records: Every transaction is permanently recorded and cannot be altered
  3. Automatic Reconciliation: Student IDs embedded in transaction memos enable automatic matching
  4. Low Fees: Stellar transactions cost a fraction of a cent
  5. Transparent Audit Trail: Anyone can verify payments on public blockchain explorers
  6. Multi-Asset Support: Accept payments in XLM (Stellar Lumens) or USDC (stablecoin)

๐ŸŒŸ How Stellar Integration Works

The Stellar Blockchain

Stellar is a decentralized, open-source blockchain network designed for fast, low-cost financial transactions. Unlike traditional payment systems, Stellar:

  • Confirms transactions in 3-5 seconds
  • Charges 0.00001 XLM per transaction (~$0.000001)
  • Supports multiple currencies (XLM, USDC, and custom tokens)
  • Provides public transaction records for transparency

Payment Flow with Stellar

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚   Parent    โ”‚
โ”‚   Wallet    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜
       โ”‚ 1. Send XLM/USDC with student ID as memo
       โ”‚
       โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚      Stellar Blockchain Network         โ”‚
โ”‚  (Transaction recorded immutably)       โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
       โ”‚ 2. Transaction confirmed in 3-5 seconds
       โ”‚
       โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚   School    โ”‚
โ”‚   Wallet    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜
       โ”‚ 3. Backend syncs from Horizon API
       โ”‚
       โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚      StellarEduPay Backend              โ”‚
โ”‚  โ€ข Reads transaction from blockchain    โ”‚
โ”‚  โ€ข Extracts memo (student ID)           โ”‚
โ”‚  โ€ข Validates amount against fee         โ”‚
โ”‚  โ€ข Updates student payment status       โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The Memo Field: Automatic Payment Matching

Stellar transactions include an optional memo field (up to 28 characters). StellarEduPay uses this to embed the student ID:

Transaction Details:
  From:   Parent's Wallet (GPARENT...)
  To:     School Wallet (GSCHOOL...)
  Amount: 250 XLM
  Memo:   "STU001"  โ† Student ID for automatic matching

When the backend syncs transactions, it:

  1. Reads the memo field
  2. Matches it to a registered student
  3. Validates the amount against the student's fee
  4. Automatically updates the payment status

No manual reconciliation needed!

Read-Only Integration

Important: The backend never holds or requires the school's private key. It only:

  • Reads transactions from the public Stellar Horizon API
  • Verifies payment amounts and memos
  • Records payment metadata in MongoDB

The school administrator controls the wallet privately through their own Stellar wallet application.

Accepted Assets

StellarEduPay accepts two types of payments:

Asset Type Description
XLM Native Stellar's native cryptocurrency (Lumens)
USDC Stablecoin USD-pegged stablecoin for price stability

Assets are configured in backend/src/config/stellarConfig.js. Additional assets can be added by updating the configuration.

Testnet vs Mainnet

  • Testnet: For development and testing (free test XLM from Friendbot)
  • Mainnet: For production with real assets

Controlled by the STELLAR_NETWORK environment variable.


โœจ Key Features

  • โœ… Blockchain-Based Payments: Immutable, transparent transaction records
  • โœ… Automatic Reconciliation: Student ID memos enable instant payment matching
  • โœ… Multi-Asset Support: Accept XLM or USDC payments
  • โœ… Fee Validation: Automatic detection of underpayments, overpayments, and exact matches
  • โœ… Payment Limits: Configurable min/max thresholds for security
  • โœ… Transaction Verification: Verify any payment by transaction hash
  • โœ… Payment History: Complete audit trail for each student
  • โœ… Retry Mechanism: Automatic retry for failed verifications during network outages
  • โœ… Background Polling: Continuous sync of new payments from the blockchain
  • โœ… RESTful API: Clean, documented endpoints for all operations
  • โœ… Comprehensive Testing: Full test coverage with Jest

๐Ÿ—๏ธ Architecture

StellarEduPay is a three-tier application:

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                     Parent/Admin Browser                      โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                         โ”‚ HTTPS
                         โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                   Next.js Frontend (React)                    โ”‚
โ”‚  โ€ข Payment forms  โ€ข Student dashboard  โ€ข Reports             โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                         โ”‚ REST API
                         โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚              Express.js Backend (Node.js)                     โ”‚
โ”‚  โ€ข Payment controller  โ€ข Stellar service  โ€ข Validation       โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
          โ”‚                                    โ”‚
          โ–ผ                                    โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”          โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚      MongoDB        โ”‚          โ”‚   Stellar Horizon API      โ”‚
โ”‚  โ€ข Students         โ”‚          โ”‚  โ€ข Transaction ledger      โ”‚
โ”‚  โ€ข Payments         โ”‚          โ”‚  โ€ข Account operations      โ”‚
โ”‚  โ€ข Fee structures   โ”‚          โ”‚  โ€ข Asset information       โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜          โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Key Components

Component Location Responsibility
Express App backend/src/app.js HTTP server, route mounting, error handling
Stellar Service backend/src/services/stellarService.js Ledger sync, transaction verification, fee validation
Stellar Config backend/src/config/stellarConfig.js Horizon server, accepted assets, network configuration
Payment Controller backend/src/controllers/paymentController.js Payment instructions, verification, sync endpoints
Student Controller backend/src/controllers/studentController.js Student CRUD, automatic fee assignment
Fee Controller backend/src/controllers/feeController.js Fee structure management
Retry Service backend/src/services/retryService.js Automatic retry for failed verifications
Transaction Service backend/src/services/transactionService.js Background polling for new payments

๐Ÿ› ๏ธ Tech Stack

Layer Technology Purpose
Blockchain Stellar Network Payment ledger and transaction processing
Backend Node.js + Express REST API server
Database MongoDB + Mongoose Student records and payment metadata
Frontend Next.js (React) User interface
Blockchain SDK Stellar SDK Horizon API integration
Testing Jest + Supertest Unit and integration tests
DevOps Docker + Docker Compose Containerization and deployment

๐Ÿš€ Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Installation

Step 1: Clone the Repository

git clone https://github.com/yourusername/StellarEduPay.git
cd StellarEduPay

Step 2: Generate a School Wallet

You need a Stellar wallet to receive payments. Generate one using the Stellar Laboratory:

Option A: Using Stellar Laboratory (Recommended for beginners)

  1. Visit Stellar Laboratory
  2. Click "Generate keypair"
  3. Copy the Public Key (starts with G...) โ€” this is your SCHOOL_WALLET_ADDRESS
  4. Securely save the Secret Key (starts with S...) โ€” never share this or commit it to version control
  5. Click "Fund account with Friendbot" to get free test XLM (testnet only)

Option B: Using the provided script

# Install backend dependencies first if you haven't already
cd backend && npm install && cd ..

node scripts/create-school-wallet.js

This will output:

Public Key:  GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Secret Key:  SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

โš ๏ธ  Save the secret key securely! The backend only needs the public key.

Step 3: Install Dependencies

Backend:

cd backend
npm install

Frontend:

cd ../frontend
npm install

Root (for tests):

cd ..
npm install

Configuration

Step 4: Configure Backend Environment Variables

Create a .env file in the backend/ directory:

Create your local environment file by copying the unified template:

cp .env.example .env

Open .env and configure your credentials (e.g., set SCHOOL_WALLET_ADDRESS slightly generated above).

For the frontend, specify the backend API URL in frontend/.env.local:

cd backend
cp .env.example .env

Edit backend/.env with your configuration:

# โ”€โ”€ Required โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
# MongoDB connection string
MONGO_URI=mongodb://localhost:27017/stellaredupay

# School's Stellar public key (from Step 2)
SCHOOL_WALLET_ADDRESS=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# โ”€โ”€ Stellar Network โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
# Use "testnet" for development, "mainnet" for production
STELLAR_NETWORK=testnet

# โ”€โ”€ Server โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
PORT=5000

# โ”€โ”€ Payment Limits (Optional) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
# Minimum payment amount in XLM/USDC
MIN_PAYMENT_AMOUNT=0.01

# Maximum payment amount in XLM/USDC
MAX_PAYMENT_AMOUNT=100000

# โ”€โ”€ Background Jobs (Optional) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
# How often to poll for new payments (milliseconds)
POLL_INTERVAL_MS=30000

# How often to retry failed verifications (milliseconds)
RETRY_INTERVAL_MS=60000

# Maximum retry attempts before giving up
RETRY_MAX_ATTEMPTS=10

Step 5: Configure Frontend Environment Variables

Create a .env.local file in the frontend/ directory:

cd ../frontend
cp .env.example .env.local

Edit frontend/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:5000/api

Running the Application

Option A: Run Locally (Development)

Terminal 1 - Start MongoDB (if running locally):

mongod --dbpath /path/to/your/data/directory

Terminal 2 - Start Backend:

cd backend
npm run dev

You should see:

MongoDB connected
Server running on port 5000
Background polling started (interval: 30000ms)
Retry worker started (interval: 60000ms)

Terminal 3 - Start Frontend:

cd frontend
npm run dev

Visit http://localhost:3000 in your browser.

Option B: Run with Docker Compose

# From the project root โ€” replace the value with your actual public key
SCHOOL_WALLET_ADDRESS=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX docker compose up --build

On older Docker installations, use docker-compose (with a hyphen) instead of docker compose.

This will start:

  • MongoDB on port 27017
  • Backend on port 5000
  • Frontend on port 3000

Initial Setup: Seed Data

Once the application is running, seed some initial data:

1. Create a fee structure:

curl -X POST http://localhost:5000/api/fees \
  -H "Content-Type: application/json" \
  -d '{
    "className": "Grade 5A",
    "feeAmount": 250,
    "description": "Annual tuition fees",
    "academicYear": "2026"
  }'

2. Register a student:

curl -X POST http://localhost:5000/api/students \
  -H "Content-Type: application/json" \
  -d '{
    "studentId": "STU001",
    "name": "Alice Johnson",
    "class": "Grade 5A"
  }'

The student's fee will be automatically assigned from the class fee structure.

3. Get payment instructions:

curl http://localhost:5000/api/payments/instructions/STU001

Response:

{
  "walletAddress": "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "memo": "STU001",
  "acceptedAssets": [
    { "code": "XLM", "type": "native", "displayName": "Stellar Lumens" },
    { "code": "USDC", "type": "credit_alphanum4", "displayName": "USD Coin" }
  ],
  "paymentLimits": {
    "min": 0.01,
    "max": 100000
  },
  "note": "Include the student ID exactly as the memo when sending payment."
}

4. Make a test payment:

Use a Stellar wallet (e.g., Stellar Laboratory) to send XLM to the school wallet address with memo STU001.

5. Sync payments:

curl -X POST http://localhost:5000/api/payments/sync

The backend will fetch recent transactions from the Stellar network and automatically match them to students.


๐Ÿ” Environment Variables

Backend Variables

Variable Required Default Description
MONGO_URI โœ… Yes - MongoDB connection string (e.g., mongodb://localhost:27017/stellaredupay)
SCHOOL_WALLET_ADDRESS โœ… Yes - School's Stellar public key (starts with G...)
STELLAR_NETWORK โœ… Yes testnet Stellar network: testnet or mainnet
PORT No 5000 Backend server port
HORIZON_URL No Auto Stellar Horizon API URL (auto-detected from network)
USDC_ISSUER No Auto USDC issuer address (auto-detected from network)
MIN_PAYMENT_AMOUNT No 0.01 Minimum payment amount in XLM/USDC
MAX_PAYMENT_AMOUNT No 100000 Maximum payment amount in XLM/USDC
POLL_INTERVAL_MS No 30000 Background polling interval (milliseconds)
RETRY_INTERVAL_MS No 60000 Retry worker interval (milliseconds)
RETRY_MAX_ATTEMPTS No 10 Maximum retry attempts for failed verifications

Frontend Variables

Variable Required Default Description
NEXT_PUBLIC_API_URL โœ… Yes - Backend API base URL (e.g., http://localhost:5000/api)

Configuration Validation

The application validates configuration on startup:

  • MIN_PAYMENT_AMOUNT must be positive (> 0)
  • MAX_PAYMENT_AMOUNT must be greater than MIN_PAYMENT_AMOUNT
  • SCHOOL_WALLET_ADDRESS must be a valid Stellar public key

If validation fails, the application will not start and will display a clear error message.


๐Ÿ“ก API Usage Examples

Students

Register a Student

POST /api/students
Content-Type: application/json

{
  "studentId": "STU001",
  "name": "Alice Johnson",
  "class": "Grade 5A"
}

Response 201:

{
  "studentId": "STU001",
  "name": "Alice Johnson",
  "class": "Grade 5A",
  "feeAmount": 250,
  "feePaid": false
}

Get All Students

GET /api/students

Get a Specific Student

GET /api/students/STU001

Fee Structures

Create a Fee Structure

POST /api/fees
Content-Type: application/json

{
  "className": "Grade 5A",
  "feeAmount": 250,
  "description": "Annual tuition fees",
  "academicYear": "2026"
}

Get All Fee Structures

GET /api/fees

Get Fee for a Class

GET /api/fees/Grade%205A

Payments

Get Payment Instructions

GET /api/payments/instructions/STU001

Response 200:

{
  "walletAddress": "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "memo": "STU001",
  "acceptedAssets": [
    {
      "code": "XLM",
      "type": "native",
      "displayName": "Stellar Lumens"
    },
    {
      "code": "USDC",
      "type": "credit_alphanum4",
      "displayName": "USD Coin"
    }
  ],
  "paymentLimits": {
    "min": 0.01,
    "max": 100000
  },
  "note": "Include the student ID exactly as the memo when sending payment."
}

Verify a Transaction

POST /api/payments/verify
Content-Type: application/json

{
  "txHash": "abc123def456..."
}

Response 200:

{
  "hash": "abc123def456...",
  "memo": "STU001",
  "amount": 250,
  "feeAmount": 250,
  "feeValidation": {
    "status": "valid",
    "message": "Payment matches the required fee"
  },
  "date": "2026-03-24T10:00:00Z"
}

Fee Validation Statuses:

  • valid: Payment exactly matches the required fee
  • overpaid: Payment exceeds the required fee (still accepted)
  • underpaid: Payment is less than required (not accepted)
  • unknown: Student not found or memo missing

Sync Payments from Blockchain

POST /api/payments/sync

Fetches the 20 most recent transactions to the school wallet, matches memos to students, validates amounts, and records new payments.

Response 200:

{
  "message": "Sync complete"
}

Get Payment History for a Student

GET /api/payments/STU001

Response 200:

[
  {
    "txHash": "abc123...",
    "amount": 250,
    "feeAmount": 250,
    "feeValidationStatus": "valid",
    "memo": "STU001",
    "confirmedAt": "2026-03-24T10:00:00Z"
  }
]

Get Accepted Assets

GET /api/payments/accepted-assets

Response 200:

[
  {
    "code": "XLM",
    "type": "native",
    "displayName": "Stellar Lumens"
  },
  {
    "code": "USDC",
    "type": "credit_alphanum4",
    "displayName": "USD Coin"
  }
]

Get Payment Limits

GET /api/payments/limits

Response 200:

{
  "min": 0.01,
  "max": 100000,
  "message": "Payment amounts must be between 0.01 and 100000"
}

Error Responses

All errors follow a consistent format:

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

Common Error Codes:

  • NOT_FOUND: Resource not found (404)
  • VALIDATION_ERROR: Invalid request data (400)
  • DUPLICATE_TX: Transaction already recorded (409)
  • TX_FAILED: Transaction failed on Stellar network (400)
  • MISSING_MEMO: Transaction missing required memo field (400)
  • INVALID_DESTINATION: Transaction sent to wrong wallet (400)
  • UNSUPPORTED_ASSET: Payment made in unsupported asset (400)
  • AMOUNT_TOO_LOW: Payment below minimum limit (400)
  • AMOUNT_TOO_HIGH: Payment exceeds maximum limit (400)
  • STELLAR_NETWORK_ERROR: Stellar Horizon API unavailable (502)

๐Ÿงช Testing

StellarEduPay includes comprehensive test coverage for all core functionality.

Run All Tests

Tests mock both the Stellar SDK and MongoDB โ€” no real network or database required.

# From the project root โ€” install root dependencies first if you haven't already
npm install

npm test

Expected output:

PASS tests/stellar.test.js
PASS tests/payment.test.js
PASS tests/payment-limits.test.js

Test Suites: 3 passed, 3 total
Tests:       45 passed, 45 total
Snapshots:   0 total
Time:        5.234s

Test Files

Test File Coverage
tests/stellar.test.js Stellar service: asset detection, fee validation, amount normalization, transaction verification, ledger sync
tests/payment.test.js Payment API: full payment flow, all endpoints, edge cases, error handling
tests/payment-limits.test.js Payment limits: validation, boundary cases, error codes

Run Specific Tests

# Test Stellar service only
npm test tests/stellar.test.js

# Test payment API only
npm test tests/payment.test.js

# Test payment limits only
npm test tests/payment-limits.test.js

Test Coverage

All tests use mocks for:

  • Stellar SDK: No real blockchain network calls
  • MongoDB: In-memory database for isolation
  • HTTP requests: Supertest for API testing

This ensures tests run quickly and don't require external dependencies.


๐Ÿ“ Project Structure

StellarEduPay/
โ”œโ”€โ”€ backend/                          # Backend Node.js application
โ”‚   โ”œโ”€โ”€ src/
โ”‚   โ”‚   โ”œโ”€โ”€ app.js                    # Express server setup
โ”‚   โ”‚   โ”œโ”€โ”€ config/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ index.js              # Environment configuration
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ stellarConfig.js      # Stellar network configuration
โ”‚   โ”‚   โ”œโ”€โ”€ controllers/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ feeController.js      # Fee structure endpoints
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ paymentController.js  # Payment endpoints
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ reportController.js   # Report generation
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ studentController.js  # Student CRUD endpoints
โ”‚   โ”‚   โ”œโ”€โ”€ middleware/
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ validate.js           # Request validation middleware
โ”‚   โ”‚   โ”œโ”€โ”€ models/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ feeStructureModel.js  # Fee structure schema
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ paymentModel.js       # Payment schema
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ paymentIntentModel.js # Payment intent schema
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ pendingVerificationModel.js # Retry queue schema
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ studentModel.js       # Student schema
โ”‚   โ”‚   โ”œโ”€โ”€ routes/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ feeRoutes.js          # Fee structure routes
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ paymentRoutes.js      # Payment routes
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ reportRoutes.js       # Report routes
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ studentRoutes.js      # Student routes
โ”‚   โ”‚   โ”œโ”€โ”€ services/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ reportService.js      # Report generation logic
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ retryService.js       # Automatic retry mechanism
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ stellarService.js     # Stellar blockchain integration
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ transactionService.js # Background polling
โ”‚   โ”‚   โ””โ”€โ”€ utils/
โ”‚   โ”‚       โ””โ”€โ”€ paymentLimits.js      # Payment limit validation
โ”‚   โ”œโ”€โ”€ .env.example                  # Example environment variables
โ”‚   โ””โ”€โ”€ package.json                  # Backend dependencies
โ”‚
โ”œโ”€โ”€ frontend/                         # Next.js frontend application
โ”‚   โ”œโ”€โ”€ src/
โ”‚   โ”‚   โ”œโ”€โ”€ components/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ Navbar.jsx            # Navigation component
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ PaymentForm.jsx       # Payment form component
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ ReportDownload.jsx    # Report download component
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ TransactionCard.jsx   # Transaction display component
โ”‚   โ”‚   โ”œโ”€โ”€ pages/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ index.jsx             # Home page
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ dashboard.jsx         # Student dashboard
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ pay-fees.jsx          # Payment page
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ reports.jsx           # Reports page
โ”‚   โ”‚   โ”œโ”€โ”€ services/
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ api.js                # API client
โ”‚   โ”‚   โ””โ”€โ”€ styles/
โ”‚   โ”‚       โ””โ”€โ”€ globals.css           # Global styles
โ”‚   โ”œโ”€โ”€ .env.example                  # Example environment variables
โ”‚   โ””โ”€โ”€ package.json                  # Frontend dependencies
โ”‚
โ”œโ”€โ”€ docs/                             # Documentation
โ”‚   โ”œโ”€โ”€ api-spec.md                   # Full API reference
โ”‚   โ”œโ”€โ”€ architecture.md               # System architecture
โ”‚   โ”œโ”€โ”€ payment-limits.md             # Payment limits documentation
โ”‚   โ””โ”€โ”€ stellar-integration.md        # Stellar integration details
โ”‚
โ”œโ”€โ”€ scripts/
โ”‚   โ””โ”€โ”€ create-school-wallet.js       # Wallet generation script
โ”‚
โ”œโ”€โ”€ tests/                            # Test suite
โ”‚   โ”œโ”€โ”€ payment.test.js               # Payment API tests
โ”‚   โ”œโ”€โ”€ payment-limits.test.js        # Payment limits tests
โ”‚   โ””โ”€โ”€ stellar.test.js               # Stellar service tests
โ”‚
โ”œโ”€โ”€ .gitignore                        # Git ignore rules
โ”œโ”€โ”€ CONTRIBUTING.md                   # Contribution guidelines
โ”œโ”€โ”€ docker-compose.yml                # Docker Compose configuration
โ”œโ”€โ”€ package.json                      # Root package.json for tests
โ””โ”€โ”€ README.md                         # This file

๐Ÿ“š Documentation

Comprehensive documentation is available in the docs/ directory:

Document Description
docs/architecture.md System design, component overview, data flow diagrams
docs/api-spec.md Complete API reference with request/response examples
docs/stellar-integration.md Stellar-specific details: memo field, assets, testnet setup
docs/payment-limits.md Payment limits feature: configuration, security, troubleshooting

๐Ÿค Contributing

We welcome contributions! Please read our Contributing Guidelines for details on:

  • Code of conduct
  • Development workflow
  • Pull request process
  • Coding standards

Quick Start for Contributors

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and add tests
  4. Run tests: npm test
  5. Commit your changes: git commit -m 'Add amazing feature'
  6. Push to the branch: git push origin feature/amazing-feature
  7. Open a Pull Request

๐Ÿ”ฎ Future Enhancements

  • Multi-School Support: Isolated wallets and records per institution
  • Email/SMS Notifications: Alert parents when payments are confirmed
  • Scholarship Disbursement: Outbound XLM payments to student wallets
  • Hostel & Exam Fees: Separate fee categories per student
  • Donation Tracking: Transparent fund collection for school projects
  • Mobile App: Native iOS/Android applications
  • Admin Dashboard: Enhanced analytics and reporting
  • Recurring Payments: Automatic payment scheduling
  • Multi-Currency Support: Additional stablecoins (EURC, etc.)

๐Ÿ“„ License

This project is licensed under the MIT License. See the LICENSE file for details.


๐Ÿ†˜ Support

If you encounter any issues or have questions:

  1. Check the Documentation
  2. Search existing issues
  3. Open a new issue with:
    • Clear description of the problem
    • Steps to reproduce
    • Expected vs actual behavior
    • Environment details (OS, Node version, etc.)

๐Ÿ™ Acknowledgments


๐ŸŒ Useful Links


Built with โค๏ธ using Stellar blockchain technology

About

No description, website, or topics provided.

Resources

Contributing

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • JavaScript 100.0%