Inspiration: The "One-Click Dispute" Realization

A few months ago, I had an issue with an online order and checked my banking app. Right there on the transaction was a simple button: "Dispute charge". Within a couple of taps, my money was refunded.

As a consumer, it felt seamless. But when I actually researched what happens on the merchant's end, I was shocked.

When a customer clicks dispute, the seller on PayPal instantly gets hit with a freeze on their funds, an automatic non-refundable chargeback fee ($15–$25), and a ticking 7-day clock to defend themselves. Even worse, if the case drags on to bank arbitration, the loser can get penalized with a $500+ scheme fee. Small business owners don't have legal teams to decode confusing Visa and Mastercard reason codes or know what "Visa Compelling Evidence 3.0" even means. Most sellers just panic, lose by default, and eat the loss.

That’s why we built ShieldAgent: to put an autonomous AI agent in the merchant's corner that detects friendly fraud, gathers proof, and fights disputes automatically through the PayPal API.


What ShieldAgent Does

When a dispute hits PayPal, ShieldAgent acts as an autonomous defense council:

  • Triage & Deadlines: Catches claims via PayPal webhooks, calculates the real win probability, and alerts on urgent Day $N-1$ deadlines so merchants never lose by default.
  • Forensic Evidence Lab: Checks tracking numbers, verifies carrier Proof of Delivery coordinates against the buyer's address, and inspects uploaded photos for digital tampering.
  • Visa CE 3.0 Engine: Automatically scans past sales. If the customer had 2 prior undisputed orders with the same IP or address, Visa rules mandate an automatic win—ShieldAgent cites the rule to force an instant liability shift back to the bank.
  • $500 Arbitration Protection: If a dispute escalates to Stage 9 Scheme Arbitration where the loser pays $500, ShieldAgent calculates the Expected Value (EV). If the math is negative, it advises conceding early to save the seller from a massive penalty.
  • One-Click PayPal Submission: Assembles the defense dossier and transmits it directly to PayPal's POST /v1/customer/disputes/{id}/provide-evidence endpoint, while generating a printable bank packet.

The Hardest Challenge: The WhatsApp Image Trap

One real problem we ran into was testing evidence photos. When we uploaded customer damage photos, our initial code failed to find camera metadata.

We quickly realized that apps like WhatsApp strip all EXIF tags and GPS data for privacy. Instead of giving up or guessing, we built a file signature detector: it recognizes WhatsApp compression, pulls the real capture date right out of the filename timeline, and flags the stripped metadata as a forensic signal.


What We're Proud Of

We didn't build another generic AI chatbot. We built a working, full-stack merchant tool that solves a real $100B enterprise pain point, passed all our end-to-end scheme tests, and connects directly to PayPal's Developer Sandbox.


What's Next

Connecting ShieldAgent directly to store platforms like Shopify and WooCommerce, so order histories and tracking receipts sync into PayPal dispute responses with zero human effort.

Built With

  • agentic-ai
  • chargebacks
  • fastapi
  • fintech
  • fraud-detection
  • multi-agent
  • paypal
  • pillow
  • pydantic
  • python
  • react
  • rest-api
  • tailwindcss
  • vite
Share this project:

Updates

Submission history