Inspiration
Small shops get refund requests all day. Each one is a judgment call, and letting an AI agent make those calls on its own is risky: it can be talked into things, and a mistake means real money. I wanted an agent that does the investigation and the writing, while something deterministic holds the money.
What it does
A buyer reports a problem with an order. An agent looks into it using read-only tools and proposes a claim type and a remedy tier. A policy engine, which is plain code, then decides: allow, require approval, or deny, and the exact amount. Only an idempotent executor can call PayPal's refund API. Anything the policy does not clearly cover goes to the merchant.
The merchant writes the policy in English. Claude Opus 5.5 compiles it into rules and generates tests, and the merchant reviews both before activating. A console shows every case: what the agent looked at, what it proposed, which rule decided, and the refund.
How I built it
AI tools used, and how:
- Claude Opus 5.5 compiles the merchant's English policy into structured rules plus generated test cases.
- Claude Sonnet 5.5 is the case agent. It has read-only tools and a single "propose a remedy" call. It sees opaque handles instead of PayPal ids, and a proposal has no amount field.
PayPal APIs used (sandbox): OAuth 2.0, Orders v2 (create and capture), Payments v2 refunds with PayPal-Request-Id, webhook signature verification, and the JavaScript SDK v6 for checkout.
The guarantees come from code, not from prompting. Precedence is deny over require-approval over allow, and no matching rule means a person decides. The executor takes a database lock, re-checks limits and reserves the amount before paying. Approvals are bound to the exact parameters and policy version, work once and expire. Money is stored as integer cents. The stack is TypeScript on Node 22, Hono, Postgres (Neon) with Drizzle, hosted on Render.
Challenges
Keeping the model out of the money path without making the agent useless. Making concurrent claims safe: the evaluation found that simultaneous claims from one buyer could slip past the per-buyer limit, a bug none of the other tests had caught. It is fixed with regression tests. I also had to handle PayPal timeouts, replayed webhooks and a free host that sleeps.
Accomplishments
152 offline tests and 60 integration tests against a real Postgres. A 30-scenario evaluation with the real agent (ordinary claims, prompt injections, split-refund sequences, ambiguous cases), each run twice. In all 60 runs no refund went beyond what the written policy allows, checked against limits written by hand from the policy text rather than against the engine's own output.
What I learned
Treating the model as an untrusted proposer simplifies the whole design. Prompt injection stops being a scary problem when the worst the model can do is propose something the engine then rules on.
What's next
PayPal dispute handling, an MCP entry point so a merchant's own agent can use the same guarded pipeline, a tamper-evident audit log, and multiple merchants.
Honest limits
The evaluation is small, uses one policy, and its labels were written by the builders. PayPal is faked inside the evaluation; the real refund path was tested separately in the sandbox. Sandbox only, one merchant. Disputes are not built.
Built With
- anthropic-claude-api
- claude-opus-5.5
- drizzle
- github-actions
- hono
- neon
- node.js
- paypal
- paypal-javascript-sdk
- paypal-rest-api
- postgresql
- render
- typescript
- vitest
- zod