Inspiration# About Dispute Defender
Inspiration
For small online sellers, handling a PayPal dispute can be stressful and time-consuming. When a buyer reports an issue such as an item not being received or a product not matching its description, the seller must gather relevant evidence, understand PayPal's requirements, and prepare a clear response within the given timeframe.
We wanted to make this process simpler.
That inspired us to build Dispute Defender — an AI-powered dispute management assistant that helps sellers organize evidence, understand what is missing, and prepare structured responses to PayPal disputes.
Our goal was not to replace the seller's judgment, but to give sellers the tools and guidance they need to respond more confidently.
What We Built
Dispute Defender connects with the PayPal Sandbox Customer Disputes API to retrieve dispute information and provide sellers with a centralized workspace.
The application follows a seller-controlled workflow:
- Sync PayPal disputes: Sellers manually synchronize their disputes from their PayPal Business Sandbox account.
- Review dispute details: The dashboard displays dispute information, buyer statements, transaction details, and requested evidence.
- Add supporting evidence: Sellers can provide tracking information, invoices, buyer-seller messages, notes, and supporting images.
- Match evidence: A rule-based evidence matching engine compares the seller's available evidence against PayPal's requested evidence and identifies missing or unverified items.
- AI-powered analysis: A locally running AI model analyzes the available dispute information and seller-provided evidence, highlighting important claims, evidence gaps, potential conflicts, and recommended next steps.
- Generate a response: The AI prepares a structured draft that the seller can review and edit.
- Seller-approved submission: Only after the seller explicitly reviews and approves the submission does Dispute Defender send the evidence to PayPal through its API.
The evidence completeness score indicates how much of the requested evidence has been provided. It does not predict the probability of winning a dispute.
How We Built It
We developed Dispute Defender as a full-stack web application.
Frontend
- React
- TypeScript
- Vite
- CSS
- Lucide React icons
Backend
- Node.js
- Express
- TypeScript
- SQLite
- Multer for evidence uploads
AI and Integration
- Ollama with the Qwen 2.5 7B model for local AI analysis
- PayPal Customer Disputes REST API
- PayPal Sandbox for testing dispute synchronization and evidence submission
The frontend communicates with the backend through REST API endpoints. The backend handles PayPal authentication, dispute synchronization, evidence management, rule-based matching, AI analysis, and submission.
We also implemented persistent storage using SQLite so dispute information and supporting evidence can be maintained locally.
Challenges We Faced
1. Integrating with PayPal Sandbox
Connecting the application to PayPal's Customer Disputes API required understanding OAuth authentication, API requests, dispute response structures, and evidence submission requirements.
We worked through the authentication and synchronization flow to retrieve actual Sandbox dispute records and display them in our application.
2. Understanding PayPal's Evidence Requirements
Different disputes can request different types of evidence. Simply checking whether a seller uploaded a document was not enough.
We built an evidence matching engine to map PayPal's requested evidence types to our internal categories. We also introduced a needs_verification status for evidence that cannot automatically be confirmed, especially tracking information.
This helped us avoid treating the presence of evidence as proof that a claim was established.
3. Making AI Analysis Reliable
AI-generated responses can be incomplete or inaccurate, especially when important evidence is missing.
We addressed this by combining deterministic, rule-based evidence checks with AI-generated analysis. The rules identify missing and unverified evidence, while the AI helps summarize the case and prepare a response.
We also made AI analysis a guided assistant rather than an autonomous decision-maker.
4. Keeping the Seller in Control
One of our most important design decisions was ensuring that AI cannot independently submit evidence or accept a dispute outcome.
The seller must review the evidence, edit the proposed response if necessary, and explicitly approve the submission. This keeps important dispute decisions under human control.
What We Learned
Building Dispute Defender helped us gain practical experience in:
- Integrating third-party REST APIs using OAuth 2.0.
- Working with PayPal Sandbox and dispute-management workflows.
- Building full-stack applications using React, TypeScript, Node.js, and Express.
- Designing evidence-matching systems using structured business rules.
- Integrating locally hosted language models into real application workflows.
- Managing uploaded evidence and persistent application data.
- Writing backend tests and handling API errors.
- Designing human-in-the-loop AI systems where users retain control over important actions.
We also learned that building a useful AI application is not just about generating intelligent responses. It requires reliable data, clear business rules, careful error handling, and appropriate human oversight.
What's Next?
We plan to improve Dispute Defender by expanding evidence-type support, improving the AI analysis experience, strengthening automated validation, and exploring secure multi-merchant integration.
Our long-term vision is to make dispute management more organized, understandable, and accessible for small online sellers.
Dispute Defender — Helping sellers turn scattered evidence into structured, informed dispute responses.