Dispute Mediator

Dispute Mediator is an AI mediator that helps PayPal sellers resolve disputes fairly: it recommends an accept, offer, or contest action with clear reasoning, and never acts without approval.

Comment

Inspiration

I started this project by scrolling through through Reddit and LinkedIn to find problem areas facing PayPal users, and the same story keeps appearing: someone has a problem with a PayPal transaction, support doesn't help, and they give up even when they may be right. I wanted to fix that, and my first idea was a buyer-side assistant.

Then I read what PayPal's APIs actually allow. There is no buyer-side API. An outside app can't read a buyer's purchases or file a dispute for them. The seller side, though, has a full Disputes API, and sellers face a hard decision between fighting, settling, or just refunding buyers? What surprised me in the sandbox is the strict order of steps that PayPal uses. Submitting evidence passes the dispute to the buyer and removes the option to make a settlement offer, so a seller who fights by reflex can lose the chance to resolve things cheaply.

So I flipped the idea. Dispute Mediator helps the seller, but its goal is a fair outcome, not a win. If the buyer is probably right, it says so and recommends settling early. If the seller has real evidence, it helps build the case. This helps sellers settle disputes in a fast and efficient manner.

What it does

  • Loads a seller's disputes from the PayPal Disputes API into a dashboard with deadlines, status, and missing evidence.
  • An AI agent reads the dispute and recommends one action: accept and refund, make a partial offer, or contest with evidence. If the right call depends on a missing fact, it asks the seller instead of guessing.
  • Every recommendation comes with plain-English reasoning, a case-strength rating, the evidence it relied on (labelled buyer, seller, or PayPal), what is missing, and the alternatives it considered. This ensures that the user has all the information they need at their disposal.
  • The seller edits the amount and note, and nothing is sent until they confirm. This ensures that the human stays in control o all actions taken.
  • A webhook emails the seller when a new dispute opens(not in current live implementation because project uses render free tier), with a button that opens the dashboard and requests a recommendation.

How Dispute Mediator was built

The app has four layers, and only one of them uses AI(cause realistically what seller wants a huge AI credit bill).

  • Rules layer (plain code): turns a raw PayPal dispute into facts, such as whose move it is, days left, which refund types PayPal currently allows, and which evidence is required.
  • Agent (Claude via the Vercel AI SDK): receives those facts plus the seller's records and returns a recommendation in a strict zod schema, so the result is a typed object and not free text.
  • Validator (plain code): rejects anything PayPal would refuse, such as a disallowed refund type, a bad or excessive amount, or a missing note.
  • Approval layer: re-fetches the dispute from PayPal(to ensure data is current), applies the seller's edits, validates again, and only then calls the API. It logs every approval.

The frontend is React, Vite, and Tailwind, with an AG Grid dashboard that has a custom theme and cell renderers. The backend is Node and Express, and it is hosted on Render. PayPal is used through the Customer Disputes REST API (list, read, offer, accept, evidence), webhooks, and the Agent Toolkit, which I used to prototype the agent-to-PayPal connection.

Challenges we ran into

  • No buyer-side API. My original plan was impossible, and I had to rethink the product around what the platform really supports.
  • Docs versus reality. PayPal's schema for accept-claim lists only a file upload, but the server rejected my request until I added a text note. I only found that by testing, so I trusted the server over the docs.
  • A hidden state machine. Every action changes which actions remain legal. An early bug treated a dispute under PayPal review as waiting on the buyer and showed an action button on a dead case. That made me read PayPal's allowed actions instead of assuming.
  • Making an AI agent safe to near money. The agent can only recommend. A validator checks every answer, and buyer and seller text is treated as untrusted. One of my test scenarios tries to inject instructions through the buyer's message(injection was handled gracefully by agent).
  • Deployment surprises. Render's free tier broke my build because of dev dependencies, and it blocks outbound email ports, so the hosted app cannot send the webhook email. The email works perfectly locally.

Accomplishments that I'm proud of

  • A design where the AI can be wrong without ever moving money, because a server-side validator and a human approval sit between the model and PayPal.
  • On nine scenarios I wrote by hand, the agent's action fell within the acceptable set for all nine, including the prompt-injection case. That is a preliminary check, not a benchmark, since I wrote the scenarios and several accept more than one answer.
  • Offers, evidence, and claim acceptance verified against the PayPal sandbox.
  • A hosted demo that works for judges with no setup and no AI cost.
  • Shipping this solo in my first hackathon.

What I learned

  • Let plain code handle what can be checked, and use the AI only for judgment.
  • Validate everything, and never trust a number that hasn't been checked.
  • When documentation and the server disagree, test and believe the server.
  • Treat all user text as untrusted when an AI reads it.
  • Design for cost and for the demo from the start.
  • Designing tests for the backend at the start enables errors to be caught early.

What's next for Dispute Mediator

  • Dispute prevention: flag orders likely to turn into disputes before the buyer files.
  • Give the agent PayPal's actual policy documents to cite(didn't do this for copyright reasons and to save on credits).
  • Document evidence uploads, such as delivery receipts and photos(didn't do to save on credits).
  • Real webhook signature verification, login, and a database.
  • A buyer-facing helper that prepares an honest, policy-grounded summary of a claim, which was my original idea.

Built With

Share this project:

Updates

Submission history