E-Commerce Fraud Detection

Machine learning system for detecting fraudulent transactions in e-commerce platforms using XGBoost and SMOTE.

Live Demo: https://ecommerce-fraud-detection-mlproject.onrender.com

Overview

This project implements an end-to-end fraud detection system that processes e-commerce transactions and outputs fraud risk predictions via a REST API. The system achieves 79.9% F1-score with 81.7% precision and 78.2% recall on test data.

Key Components:

Data analysis notebooks exploring 299,695 transactions
Feature engineering pipeline (17 raw → 56 engineered features)
5 models tested, XGBoost + SMOTE selected
Flask REST API with 4 endpoints
Interactive web UI for testing
Dockerized deployment on Render cloud platform

Interactive web interface - Try it live | Deployment guide

Dataset

Source: Kaggle E-Commerce Fraud Detection Dataset

Characteristics:

Size: 299,695 transactions from 6,000 users
Fraud Rate: 2.21% (6,633 fraudulent, 293,062 legitimate)
Features: 17 raw features (amount, distance, security flags, geography, time)
Split: 80% train (239,756), 20% test (59,939) with stratified sampling

The dataset is synthetic but models realistic fraud patterns including night-time spikes, geographic risk variations, and security check failures. See Datacard.txt for details.

Methodology

1. Exploratory Data Analysis

Notebook: notebooks/02_eda.ipynb

Key Findings:

Finding	Value	Insight
Shipping Distance	+0.27 correlation	Distant shipping increases fraud risk
Transaction Amount	+0.20 correlation	Higher amounts more frequently fraudulent
Security Checks	-0.22 correlation	Failed AVS/CVV strongly indicates fraud
Channel Risk	Web 4.5x app	Web transactions riskier than mobile
Geographic	Varies by country	TR, RO, PL show highest fraud rates
Temporal	Night spikes	11 PM - 6 AM elevated fraud activity

Visualizations:

Dataset imbalance: 2.21% fraud rate

Feature correlations with fraud target

Fraud rates by category (channel, country, merchant)

2. Feature Engineering

Notebook: notebooks/03_preprocessing.ipynb

Created 21 engineered features across 7 categories:

Category	Features	Examples
Distance	3	`is_distant_shipping`, `log_shipping_distance`, `distance_amount_interaction`
Amount	4	`log_amount`, `amount_zscore`, `is_high_amount`, `amount_to_avg_ratio`
Security	3	`security_score` (AVS + CVV + 3DS), `no_security_checks`, `all_security_passed`
Account	3	`is_new_account`, `log_account_age`, account maturity bins
Geographic	2	`is_high_risk_country`, `is_cross_border`
Temporal	4	`hour`, `day_of_week`, `is_weekend`, `is_odd_hour`
Channel	2	`is_web_channel`, `web_high_amount`

Total Features: 56 (17 raw + 21 engineered + 18 one-hot encoded)

3. Model Training

Notebook: notebooks/04_modeling.ipynb

Models Evaluated:

Model	F1-Score	Precision	Recall	Training Time
Logistic Regression	0.294	0.178	0.835	40.0s
Random Forest	0.487	0.334	0.902	3.1s
LightGBM	0.472	0.319	0.905	10.8s
XGBoost	0.499	0.345	0.902	0.6s
XGBoost + SMOTE	0.799	0.817	0.782	1.4s

Winner: XGBoost + SMOTE (60% improvement over base XGBoost)

F1-Score comparison across all models

Final Model Performance

Metrics (Test Set, 59,939 transactions):

F1-Score: 79.9%
Precision: 81.7% (only 18.3% of fraud alerts are false)
Recall: 78.2% (catches 78.2% of actual fraud)
False Alarm Rate: 0.33% (33 false alerts per 10,000 legitimate transactions)
PR-AUC: 84.3%

Confusion Matrix:

                 Predicted
              Legit    Fraud
Actual Legit  57,651   1,022  (98.3% correct)
       Fraud     289   1,059  (78.6% caught)

Precision-recall trade-off (AUC = 0.843)

Feature Importance (Top 5):

distance_amount_interaction (8.2%)
security_score (6.4%)
amount (6.1%)
is_distant_shipping (5.8%)
shipping_distance_km (5.6%)

Top 20 most important features

Model Selection Rationale:

Handles class imbalance with SMOTE
Best precision-recall balance (high precision reduces false alarms)
Fast training (1.4s) and inference (<50ms)
Robust to feature interactions

Full experiment details: docs/MODEL_EXPERIMENTS.md

Model Selection Trade-offs

The choice between models depends on your specific constraints around fraud costs, operational capacity, and compute resources:

Model	Best For	Why
XGBoost (base)	High-volume, limited review capacity	90% recall catches most fraud, but 271K false alarms/million tx requires massive review team
XGBoost + SMOTE	Balanced operations	78% recall with only 27K false alarms/million tx - sustainable review load
Logistic Regression	Minimal compute, rapid deployment	40s training, instant inference, but 82% false positive rate makes it impractical

When to choose each:

High fraud costs, unlimited review capacity → XGBoost (base)

Catch 90% of fraud but handle 10x more false alarms
Example: High-value luxury goods where each fraud costs $10K+

Balanced operations → XGBoost + SMOTE ⭐ (selected)

Optimal precision-recall balance (82% precision, 78% recall)
Manageable false alarm rate (0.33% of legitimate transactions)
Example: General e-commerce with moderate fraud impact

Rapid prototyping, minimal resources → Logistic Regression

40s training enables quick iteration
Useful for initial fraud signal detection before building full pipeline
Too many false alarms for production without additional filtering

Compute-constrained, real-time critical → XGBoost (base, no SMOTE)

0.6s training vs 1.4s with SMOTE
<50ms inference
Example: Payment gateway with millions of daily transactions

The key insight: Model selection isn't about absolute performance but matching operational constraints (review capacity, fraud tolerance, compute budget) to model characteristics (precision/recall trade-off, training time, inference speed).

API Documentation

Base URL: https://ecommerce-fraud-detection-mlproject.onrender.com

Endpoints

`GET /`

Returns interactive web UI for testing fraud detection.

`GET /health`

Health check and model status.

Response:

{
  "status": "healthy",
  "model": "XGBoost",
  "features": 56,
  "version": "1.0.0"
}

`POST /predict`

Predict fraud for a single transaction (requires all 56 features).

Response:

{
  "prediction": 0,
  "fraud_probability": 0.1234,
  "risk_level": "low",
  "recommendation": "approve"
}

Risk Levels:

low (<30%) → approve
medium (30-60%) → review
high (60-90%) → review
critical (>90%) → decline

`POST /predict/batch`

Batch predictions (max 1,000 transactions).

`GET /model/info`

Model metadata and performance metrics.

Complete API Guide: TESTING_GUIDE.md

Installation & Setup

Prerequisites

Python 3.11 or higher
4GB RAM minimum
Docker (optional)
Kaggle account (for dataset)

1. Clone Repository

git clone https://github.com/Dannycesp/ecommerce-fraud-detection-mlproject.git
cd ecommerce-fraud-detection-mlproject

2. Environment Setup

Option A: Using UV (Recommended)

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # Unix/Mac
# .venv\Scripts\activate   # Windows

uv pip install -r requirements.txt

Option B: Using pip

python -m venv .venv
source .venv/bin/activate  # Unix/Mac
# .venv\Scripts\activate   # Windows

pip install -r requirements.txt

3. Get Dataset

Option A: Using Kaggle API with .env (Recommended)

# 1. Get API token from https://kaggle.com/account → Create New API Token
# 2. Create .env file in project root:
echo "KAGGLE_USERNAME=your_username" > .env
echo "KAGGLE_KEY=your_api_key" >> .env

# 3. The notebooks will automatically download data using these credentials

Option B: Manual Download

# 1. Download from: https://www.kaggle.com/datasets/umuttuygurr/e-commerce-fraud-detection-dataset
# 2. Extract to: data/raw/fraud_dataset.csv
# 3. Run notebooks starting from 02_eda.ipynb

4. Run Notebooks

# Start Jupyter Lab
jupyter lab

# Execute notebooks in order:
# 1. notebooks/01_data_exploration.ipynb  (downloads data)
# 2. notebooks/02_eda.ipynb
# 3. notebooks/03_preprocessing.ipynb
# 4. notebooks/04_modeling.ipynb

Outputs:

data/processed/train.csv, data/processed/test.csv
models/fraud_detection_model.pkl (2.1 MB)
models/model_metadata.pkl

5. Run API Server

# Start Flask server
python src/serve.py
# Server runs at http://localhost:9696

# Test in another terminal
curl http://localhost:9696/health
python test_api.py

Docker Deployment

Build and Run

# Build image
docker build -t fraud-detection:latest .

# Run container
docker run -d -p 9696:9696 --name fraud-api fraud-detection:latest

# Check logs
docker logs fraud-api

# Test
curl http://localhost:9696/health

# Stop
docker stop fraud-api

Image Size: ~1.2 GB (includes Python 3.11, dependencies, model)

Cloud Deployment (Render)

Deploy to Render

Push code to GitHub
Go to https://render.com → Sign in
New → Web Service → Connect repository
Render auto-detects render.yaml configuration
Click "Create Web Service"
Wait 3-5 minutes for build

Live URL: https://ecommerce-fraud-detection-mlproject.onrender.com

Note: Free tier spins down after 15 minutes idle (30-60s cold start on first request).

Deployment Guide: docs/DEPLOYMENT.md

Deployed Web Interface

Pre-loaded test scenarios with instant fraud detection

Real-time risk gauge and prediction results

Testing

Automated Tests

# Test local API
python test_api.py

# Test Render deployment
./test_render.sh https://ecommerce-fraud-detection-mlproject.onrender.com

Web UI

Open index.html in browser for interactive testing with:

4 pre-loaded scenarios (safe, suspicious, high-risk, high-value)
Custom JSON editor
Visual risk gauge
Color-coded results

Live UI: https://ecommerce-fraud-detection-mlproject.onrender.com

Project Structure

ecommerce-fraud-detection-mlproject/
├── notebooks/                    # Jupyter notebooks
│   ├── 01_data_exploration.ipynb
│   ├── 02_eda.ipynb
│   ├── 03_preprocessing.ipynb
│   └── 04_modeling.ipynb
│
├── src/                          # Python source code
│   ├── train.py                  # Training pipeline
│   ├── predict.py                # Prediction functions
│   └── serve.py                  # Flask API server
│
├── models/                       # Trained models (gitignored)
│   ├── fraud_detection_model.pkl
│   └── model_metadata.pkl
│
├── data/                         # Datasets (gitignored)
│   ├── raw/                      # Original Kaggle data
│   └── processed/                # Train/test splits
│
├── docs/                         # Documentation
│   ├── images/                   # Visualizations (19 PNGs)
│   ├── DEPLOYMENT.md             # Deployment guide
│   └── MODEL_EXPERIMENTS.md      # Experiment log
│
├── index.html                    # Web UI
├── test_api.py                   # API tests
├── test_render.sh                # Render tests
│
├── Dockerfile                    # Container definition
├── render.yaml                   # Render config
├── requirements.txt              # Dependencies (pip/Docker)
├── pyproject.toml                # Dependencies (UV)
│
├── Datacard.txt                  # Dataset description
├── TESTING_GUIDE.md              # API testing guide
└── README.md                     # This file

Technology Stack

Core:

Python 3.11
scikit-learn 1.8.0 (preprocessing, metrics)
XGBoost 3.1.2 (model)
pandas 2.3.3, numpy 2.4.0
imbalanced-learn 0.14.1 (SMOTE)

API:

Flask 3.1.2
Flask-CORS 4.0.0

Deployment:

Docker (containerization)
Render (cloud hosting)

Development:

Jupyter Lab (analysis)
UV (dependency management)

Limitations

Synthetic Data: Dataset is not from real transactions. Real deployment requires retraining on actual fraud data.
Feature Requirements: All 56 features required for prediction. Missing features cause errors.
Static Model: No online learning. Requires manual retraining and redeployment.
Cold Starts: Render free tier spins down after 15 min idle (30-60s first request).
No Authentication: Public API without rate limiting or API keys.
Scale: Tested up to 1,000 transactions/batch, not validated for millions daily.

Future Improvements

Add SHAP values for prediction explainability
Implement API authentication (JWT)
Add rate limiting
Support partial feature sets (imputation)
Online learning for model updates
CI/CD with GitHub Actions
A/B testing framework
Multi-model ensemble

Contributing

Contributions welcome! Fork the repository, create a feature branch, and submit a pull request.

Development Setup:

# Install dependencies
uv pip install -r requirements.txt

# Run tests
python test_api.py

# Format code
black src/ test_api.py
ruff check src/

License

To be added.

Acknowledgments

Dataset: Kaggle E-Commerce Fraud Detection
Hosting: Render (free tier cloud deployment)

Contact

Author: Dannycesp GitHub: @Dannycesp Repository: ecommerce-fraud-detection-mlproject Live API: https://ecommerce-fraud-detection-mlproject.onrender.com

Last Updated: January 2026

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
data/sample		data/sample
docs		docs
models		models
notebooks		notebooks
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
Datacard.txt		Datacard.txt
Dockerfile		Dockerfile
README.md		README.md
TESTING_GUIDE.md		TESTING_GUIDE.md
index.html		index.html
pyproject.toml		pyproject.toml
render.yaml		render.yaml
requirements.txt		requirements.txt
test_api.py		test_api.py
test_render.sh		test_render.sh

Folders and files

Latest commit

History

Repository files navigation