Dispute Defence agent

Inspiration

Small businesses selling through PayPal can face disputes that are difficult and time-consuming to handle. When a customer raises a dispute, the seller must understand the claim, collect relevant evidence, meet deadlines, and prepare a clear response.

We wanted to build more than another AI response generator. We focused on a more important question:

Is this dispute actually worth fighting?

That idea inspired Dispute Defense Agent — an AI-powered assistant designed to help PayPal merchants make informed decisions before responding to disputes.

What We Built

Dispute Defense Agent helps merchants understand and manage their PayPal disputes through a single dashboard.

Key features include:

Dispute Dashboard: Displays dispute information, deadlines, and money at risk using available PayPal Sandbox data and clearly identified demo data.
AI Dispute Analysis: Uses Gemini 2.5 Flash to analyze dispute claims and the evidence provided by the seller.
Claim-Evidence Matrix: Organizes evidence into supporting, contradictory, missing, and unverified categories.
Worth Fighting Engine: Recommends whether to contest a dispute, gather more evidence, contest with caution, or consider accepting the claim. Its estimates are heuristic guidance, not guaranteed win probabilities.
Evidence Manager: Allows sellers to provide order details, tracking information, customer communication, and supporting documents.
Defense Response Generator: Creates a structured draft response based on the dispute and available evidence.
Seller-Controlled Workflow: Keeps the seller in control of the final decision and requires confirmation before attempting a supported Sandbox evidence submission.

How We Built It

We built the application using a full-stack architecture:

React 19 and TypeScript for the interactive dashboard.
Node.js and Express 5 for backend APIs and application logic.
PayPal Sandbox Disputes API for dispute-related integration.
OAuth 2.0 for PayPal API authentication.
Gemini 2.5 Flash for dispute analysis and defense response generation.
Vite for frontend development and builds.
Vitest and custom tests for validating application functionality.

The backend retrieves available dispute information from PayPal Sandbox. Sellers can then add supporting information and documents. The AI analyzes the claim against the available evidence, identifies gaps and contradictions, recommends a course of action, and prepares a defense draft.

We also implemented a rules-based fallback for situations where AI analysis is unavailable. The application distinguishes seller-reported information from independently verified information so that users can understand the source of their evidence.

Challenges We Faced

One of our biggest challenges was making AI recommendations useful without making them misleading. A dispute outcome depends on many factors, so we designed the recommendation engine to provide heuristic guidance rather than presenting an unvalidated estimate as a guaranteed probability.

Another challenge was integrating with the PayPal Sandbox Disputes API and handling authentication, dispute data, deadlines, and evidence-submission requirements.

We also had to distinguish between actual PayPal Sandbox data and locally recorded demo data. This helped us avoid presenting simulated actions as successful PayPal submissions.

Finally, designing the evidence workflow required careful attention to seller control. The AI can analyze and draft, but the seller reviews the response and remains responsible for the final action.

What We Learned

Through this project, we gained practical experience with:

Integrating third-party APIs using OAuth 2.0.
Building full-stack applications with React, TypeScript, Node.js, and Express.
Using large language models for structured analysis and content generation.
Designing AI-assisted decision workflows with human approval.
Handling evidence sources, validation, deadlines, and error cases.
Testing backend APIs and frontend functionality.

Most importantly, we learned that building a useful AI product is not just about generating intelligent answers. It is also about transparency, reliability, and keeping users in control.

What's Next

We plan to improve the project by adding verified carrier-tracking integrations, connecting order-management platforms, retrieving customer communication from supported sources, and validating recommendations against real dispute outcomes.

We also want to expand end-to-end testing with valid PayPal Sandbox disputes to further verify the evidence-submission workflow.

Our goal is simple: help small merchants make smarter dispute decisions, spend less time preparing responses, and stay in control of their business.