Inspiration

I built and ran a small pet battle web game on my own, from the client to the server, payments included. The code was the easy part. The part nobody warned me about was refund mail. Each one meant opening the payment dashboard, finding the order, checking whether the player had already spent the in-game currency, rereading my own refund rules and writing a reply. It took ten minutes per message, and the messages came at night.

Most AI commerce demos help the buyer spend. I wanted the opposite end: help the one-person seller handle the money going back, without handing the decision to a model.

What it does

RefundClerk has two sides.

Customer side. A demo shop for a tiny game called Moonpaw sells gem packs and a season pass through PayPal Checkout (sandbox). After paying, the buyer can spend gems or play sessions, then send a refund request in plain words.

Seller desk. Each request lands in an inbox. The seller's refund policy is a plain text box. Pressing Review with agent runs an agent with three tools:

  • lookupOrder reads the live order from PayPal Orders v2: status, capture, amount, refunds already made, days since payment.
  • lookupUsage reads the game's own record of how much of the item was used.
  • submitDecision returns full refund, partial refund, decline or ask the customer, with the amount, the exact policy lines used, the facts it relied on and a short reply draft.

The seller can change the amount or the reply, then press Refund via PayPal. Only then does the server call the refund API.

In the demo video, a buyer spends 300 of 500 gems and asks for the rest back. The agent finds the policy line for partly used packs, computes 200/500 of $4.99, rounds down to $1.99, and the seller approves. PayPal returns the refund ID and the order shows $3.00 still refundable.

How I built it

  • Plain HTML, CSS and JavaScript for the app, Vercel serverless functions for the API.
  • PayPal JavaScript SDK buttons for checkout. POST /v2/checkout/orders with a fixed server-side price and a digital goods line item, POST /v2/checkout/orders/{id}/capture, GET /v2/checkout/orders/{id} for the agent, and POST /v2/payments/captures/{id}/refund with a PayPal-Request-Id so a double click cannot refund twice.
  • The agent loop uses the Vercel AI SDK (generateText with tools and a stop condition on submitDecision) and Google Gemini models. If one model is busy, it falls back to the next.
  • I used Claude as a coding assistant while building.

Guardrails

The model never gets a tool that moves money. The server checks every proposed amount against what PayPal says is still refundable and lowers it if needed. It refuses refunds on uncaptured or fully refunded payments, and the refund endpoint reads the order again right before refunding.

Challenges

The first model provider I tried needed a card on file for its free credits, so I switched to Gemini on the free tier. The busier Gemini models sometimes return 503, and the first version waited minutes on retries. I added a short timeout per model and a fallback list, so a review now finishes in seconds.

What I learned

Making the agent quote the policy line it used changed how much I trusted its answer. A number with a quoted rule takes a few seconds to check. A number alone makes you redo the work.

What's next

Webhooks for disputes, so the same desk can prepare evidence when a chargeback opens, and reading usage from a real game database instead of the demo's browser storage.

Try it

Share this project:

Updates

Submission history