Inspiration

A small online shop loses a chargeback three ways, and only one of them is fraud.

  • Cases are lost by default. The evidence sits in four places (the order, the payment, the tracking, the emails) and takes about forty minutes to gather. When disputes are someone's fourth job, the deadline passes and the case closes on silence.
  • Winnable cases aren't always worth winning. A $68 claim costs the same forty minutes as a $680 one. Nobody does that arithmetic.
  • The same loss repeats. Five "item not received" claims on apartment deliveries without a signature, nothing changes, and the sixth arrives.

Most chargebacks aren't stolen cards. They're a parcel that stopped moving, a renewal someone forgot, a duplicate charge. A fraud score at checkout can't see any of that. Something watching the whole life of an order can.

What it does

AEGIS is four AI agents in one loop: prevent, intervene, defend, learn.

  • Sentinel scores every order before it ships (payer history, amount, address, velocity) and recommends ship, verify or hold, listing each signal and how much it added.
  • Interceptor watches after payment for early warning signs: tracking that hasn't moved, a missed delivery date, a renewal after months of silence, a duplicate charge. It drafts a message to the buyer before they go to their bank.
  • Advocate rebuilds a filed dispute from PayPal's own records, checks the evidence that matters for that reason code, and decides in dollars whether fighting is worth it:

$$\text{cost of fighting} = (1 - p) \times (\text{claim} + \text{fee}) + \text{staff time}$$

$$\text{cost of accepting} = \text{claim} + \text{handling}$$

where p is the chance of winning. Accepting is a real answer: on the demo data it says don't fight on 6 of 12 open disputes.

Accepting is a real answer: on the demo data it says don't fight on 6 of 12 open disputes.

  • Learner reads lost disputes, finds the pattern, and proposes a prevention rule in plain words, citing at least three past disputes it would have prevented. Nothing changes until the merchant approves it. Then Sentinel enforces it on the next order.

That last arrow, from a lost dispute back to prevention, is the product. Every dispute leaves a lesson.

How we built it

Arithmetic for decisions. AI for language. Humans for control.

  • Scores and dollar figures never come from a model. Risk scores and expected values are plain arithmetic over facts the system can point to. The same inputs give the same score every time, and "why did you hold my order?" gets a list of weighted signals. The AI writes the words: explanations, buyer messages, response letters, rule proposals.
  • The Learner can only write rules it's allowed to write. It composes conditions from a fixed set of predicates, every proposal must cite at least three recorded disputes, and duplicates are rejected in code. A rule can't do anything the merchant didn't approve.
  • Safe defaults from PayPal's own guidance. Auto-accepting a claim is off unless the merchant sets a ceiling; responses to disputes always need a human; refunds without approval are capped at $25.
  • Every record says where it came from: live from the PayPal sandbox, or simulated. The console badges simulated rows.
  • PayPal integration: Orders, Payments and refunds, Disputes (read, accept, provide evidence, provide supporting info), Transaction Search, Shipment Tracking, Invoicing, Catalog, Subscriptions and Webhooks (signature verified on the raw body, deduplicated, answered fast). One client handles tokens, retries and once-only keys on payment writes. PayPal's MCP server (@paypal/mcp) is a selectable transport for the operations it covers.
  • Pluggable AI: Claude (Anthropic), any model on OpenRouter, or Ollama (local or cloud), chosen by one setting. The rule shown in the video was worded by DeepSeek V4 Flash via OpenRouter; the drafts shown were written by Qwen3-VL 4B running locally. With no AI at all, three of the four agents still work.
  • Stack: Next.js 14, React, TypeScript, Postgres with Prisma, Zod, AG Grid for the operator queues. One Docker image serves the console and the API; the hosted demo runs on Coolify.
  • Built with AI help: Claude Code for development, with PayPal's AI Toolkit plugin (/paypal:doctor and its best-practices reference); ElevenLabs for the video narration.

Challenges we ran into

  • Getting a real dispute in the sandbox. Our first test shop was in India and couldn't receive US dollars. A US test shop fixed it, and a sandbox buyer could then pay and open a case. That case skipped the inquiry stage and went straight to chargeback, where PayPal takes "supporting info" instead of typed evidence, so Fight had to learn both channels.
  • PayPal names reasons differently from us (MERCHANDISE_OR_SERVICE_NOT_RECEIVED vs ITEM_NOT_RECEIVED), so live cases would have been counted apart from the history until we normalised them.
  • Two webhook security bugs. A boolean setting parsed "false" as true, which would have switched off signature checks; and an unverified request could block the genuine event by reusing its id. Both fixed, after PayPal's AI Toolkit flagged them.
  • Our auto-accept went against PayPal's guidance, which says never to accept a claim without review. It's now off by default.
  • Empty AI letters. Some model hosts spent the whole word budget on hidden reasoning and returned nothing. We switched reasoning off for short writing jobs and treat an empty reply as a failure to retry.
  • PayPal's hosted MCP server reports write failures as ok:false inside a successful response, so we check the payload, not just the status.

Accomplishments that we're proud of

  • A real PayPal sandbox dispute, defended end to end. A sandbox buyer paid $236 for an order and opened case PP-R-BVX-10196584 ("item not received"). Aegis pulled it in, matched it to the order, scored the evidence at 85% (a 62% chance to win, an expected cost of $114.56 to fight versus $238 to refund) and recommended Fight. A person pressed Fight, and Aegis filed the evidence and tracking at PayPal through the Disputes API on 5 Nov. The case is awaiting PayPal's decision. (The tracking number was generated by our test script and reported to PayPal as delivered; no parcel was shipped.) On a second real case with no order or tracking behind it, Aegis recommends accepting.
  • The loop closes. A rule the Learner proposed from past losses was approved in the console, and Sentinel held the next matching order because of it.
  • Results on the demo merchant (90 days of simulated history, labelled as such): $2,984 deflected before any dispute was filed across 8 interventions, $899 kept by defending 7 cases, 7 of 49 orders held before shipping.
  • It runs without keys. With no PayPal credentials and no AI, the console, the demo data and three of the four agents still work, and a hosted copy boots itself with demo data.

What we learned

The interesting part of an AI agent is the governance, not the autonomy. Spending limits, a closed rule language, citation rules, provenance on every record and an audit trail are what make it usable by someone whose money it is spending.

We also learned to trust PayPal's records over our own assumptions: the sandbox can create real disputes, chargeback-stage cases take a different response, and reason names need mapping before history and live cases agree.

What's next for AEGIS

  • Recording real won/lost outcomes from PayPal as they arrive, so the Learner learns from live losses.
  • Pre-chargeback alerts, where a refund within hours avoids the fee entirely.
  • Offering partial refunds and buyer messages at the dispute stages where PayPal allows them.

Team: Balaji P (the product: idea, agents, PayPal and AI plumbing, safety) and Yoghesh V (the experience: redesign, live sandbox disputes end to end, OpenRouter, hosting).

Built With

Share this project:

Updates

Submission history