Chargeback Assistant: An AI-Powered Chargeback Risk System
Chargeback AI
Chargebacks are a common problem for online businesses. When a customer disputes a payment, the merchant needs to decide whether to fight the dispute, accept the loss, or collect more evidence.
To solve this problem, I developed Chargeback Assistant, an AI-assisted system that helps merchants analyze chargeback disputes and make better decisions.
The system predicts the probability of winning a dispute, explains the important factors behind the prediction, and provides a recommendation.
What is a Chargeback?
A chargeback happens when a customer disputes a transaction through their bank or payment provider.
For example, a customer may claim:
The product was not delivered
The transaction was unauthorized
The customer did not receive the expected product
A refund was not received
The merchant then needs to investigate the case and provide evidence.
Handling many disputes manually can be difficult and time-consuming.
My Solution
I built Chargeback Assistant to make this process easier.
The system takes chargeback information and uses a Machine Learning model to calculate the win probability of the dispute.
Based on the result, it recommends one of three actions:
Fight the dispute
Accept liability
Gather more evidence
The basic workflow is:
Chargeback
↓
Machine Learning Prediction
↓
Win Probability
↓
SHAP Explanation
↓
LangGraph Investigation
↓
Recommendation
Machine Learning
For prediction, I used XGBoost with scikit-learn.
The model considers chargeback-related information such as:
Reason code
Delivery evidence
Signature evidence
AVS match
CVV match
Refund status
Previous chargeback history
The target variable is:
won_dispute
where:
1 = Merchant won
0 = Merchant lost
The current project uses a synthetic dataset for demonstration.
Explainable AI with SHAP
A Machine Learning model gives a prediction, but it is also important to understand why the model made that prediction.
For this, I used SHAP.
SHAP identifies the features that contributed to the prediction.
For example:
Delivery confirmed → Positive
Signature available → Positive
CVV matched → Positive
Previous chargebacks → Negative
This helps the analyst understand the reason behind the prediction instead of treating the model as a black box.
LangGraph Agent
I also used LangGraph to create an investigation workflow.
The workflow contains three steps:
Analyze Risk
↓
Explain Factors
↓
Recommend Action
The agent uses the model result and SHAP factors to create a structured investigation trace.
The recommendation can be:
FIGHT
ACCEPT LIABILITY
or
GATHER MORE EVIDENCE
The workflow is deterministic, so the project can run without requiring an LLM API key.
React Frontend
I developed the frontend using React and Tailwind CSS.
The application includes pages such as:
Login
Dashboard
Chargebacks
Chargeback Details
New Chargeback
Analytics
Audit Logs
The frontend communicates with the FastAPI backend using APIs.
Charts are created using Recharts to display chargeback analytics.
FastAPI Backend
The backend was developed using FastAPI.
It provides APIs for:
User registration and login
Chargeback prediction
Viewing chargebacks
Updating chargeback status
Audit logs
Analytics
FastAPI also provides interactive Swagger documentation.
http://localhost:8000/docs
PostgreSQL Database
I used PostgreSQL to store application data.
The database stores information such as:
Users
Chargebacks
Predictions
Audit logs
SQLAlchemy is used to communicate with the database from the FastAPI backend.
JWT Authentication
For authentication, I implemented JWT-based authentication.
The basic flow is:
Register
↓
Login
↓
JWT Token
↓
Access Protected APIs
This helps protect the application's API endpoints.
Docker
I also used Docker and Docker Compose to run the project.
The application contains multiple services:
React Frontend
↓
FastAPI Backend
↓
PostgreSQL
Docker makes it easier to set up and run all these components together.
The complete application can be started using:
docker compose up --build
The application runs at:
Frontend → http://localhost:5173
Backend → http://localhost:8000
Swagger → http://localhost:8000/docs
Technology Stack
| Technology | Purpose |
|---|---|
| React | Frontend |
| Tailwind CSS | UI styling |
| FastAPI | Backend API |
| PostgreSQL | Database |
| SQLAlchemy | Database ORM |
| XGBoost | Machine Learning |
| scikit-learn | ML processing |
| SHAP | Explainable AI |
| LangGraph | Investigation workflow |
| JWT | Authentication |
| Recharts | Data visualization |
| Docker | Containerization |
| Docker Compose | Service management |
What I Learned
This project helped me understand how different technologies can be combined to build a complete AI application.
I learned about:
Machine Learning
Explainable AI
AI agents
REST APIs
React
PostgreSQL
JWT authentication
Docker
Full-stack application development
The biggest lesson I learned was that an AI application should not only give a prediction, but should also explain the prediction and help the user take action.
Future Improvements
In the future, I would like to improve the project by:
Using real historical chargeback data
Improving model accuracy and validation
Adding LLM-generated investigation summaries
Adding evidence/document upload
Adding better role-based authorization
Adding model monitoring
Supporting multiple merchants
Conclusion
Chargeback Assistant combines Machine Learning, Explainable AI, and an agent workflow to help merchants analyze chargeback disputes.
Instead of simply saying that a transaction is risky, the system focuses on a more useful question:
How likely is the merchant to win the dispute?
The project gave me practical experience in building an AI-powered full-stack application using React, FastAPI, XGBoost, SHAP, LangGraph, PostgreSQL, JWT, and Docker.
I am excited to continue improving this project and explore more real-world applications of AI.
Project
GitHub: github.com/devisri424/chargeback-assistant
Live Demo Video: Watch the Live Demo
Thanks for reading! ❤️
