Merchant Shield AI

An AI-powered dispute defense copilot using dual-engine rules & Gemini 3.8 Flash to automate PayPal chargeback resolution.

Comment

Inspiration

Merchants lose billions of dollars annually to chargebacks—not because customer claims are valid, but because dispute management is slow, manual, and legally cumbersome. Gathering carrier tracking, cross-referencing PayPal Seller Protection guidelines, and writing formal rebuttal letters takes hours per dispute. We built Merchant Shield AI to compress that workflow from hours into under 15 seconds, giving merchants an automated defense copilot to protect their revenue.

What it does

Merchant Shield AI functions as an end-to-end dispute defense copilot for PayPal merchants:

  • Instant Webhook Sync: Automatically ingests PayPal customer dispute events (CUSTOMER.DISPUTE.CREATED).
  • Deterministic Policy Triage: Evaluates order details, carrier delivery logs, and recipient postal codes against PayPal Seller Protection criteria to issue an immediate verdict (STRONG FIGHT, RISKY, or NO FIGHT).
  • Fact-Grounded AI Rebuttal Drafts: Leverages Google Gemini 3.8 Flash to draft formal rebuttal letters grounded exclusively in verified internal database records—eliminating AI hallucinations.
  • Human-in-the-Loop Review: Provides an intuitive dashboard for merchants to inspect rules verification, edit AI rebuttal drafts live, and approve submissions.
  • Automated Evidence Packets: Generates downloadable ReportLab PDF packets and prepares API payloads for PayPal's dispute endpoints.

How I built it

  • Backend & Database: Built using Python, FastAPI, and SQLite managed via SQLAlchemy.
  • AI Integration: Integrated Google Gemini 3.8 Flash API with strict evidence-vault prompt constraints.
  • Payment & Webhooks: Integrated PayPal Developer Sandbox API endpoints and signature-verified webhook handlers.
  • PDF & UI: Used ReportLab for dynamic PDF packet generation, and Jinja2 with Tailwind CSS for the merchant dashboard UI.

Challenges I ran into

The biggest challenge was balancing open-ended LLM text generation with strict payment policy requirements. Generative AI alone can hallucinate policy claims that invalidate a dispute response. We resolved this by building a Dual-Engine Architecture: the deterministic rules engine establishes verified facts first, and Gemini 3.8 Flash translates those structured facts into convincing narrative rebuttals.

Accomplishments that I'm proud of

  • Delivering a fully functional, end-to-end dispute defense workflow as a solo developer project.
  • Achieving a complete execution cycle—from webhook ingestion to policy evaluation, AI draft generation, and PDF compilation—in under 15 seconds.
  • Building a robust architecture with clean database schema separation, open-source licensing (MIT), and complete setup reproducibility.

What I learned

  • How to structure hybrid AI systems that combine deterministic business logic with LLM generative capabilities safely.
  • Deepened hands-on experience with PayPal Sandbox API integration, webhook authentication, and Seller Protection compliance workflows.
  • Dynamic PDF generation techniques using Python's ReportLab for official evidence packet creation.

What's next for Merchant Shield AI

  • Automated live carrier API tracking synchronization (USPS, FedEx, DHL, and UPS).
  • Multi-currency chargeback analytics dashboard with automated dispute risk forecasting.
  • One-click bulk approval workflows for merchants handling high-volume daily disputes.

Built With

Share this project:

Updates

Submission history