Clearline

Every PayPal payment on one clear line. Buyers ask before they dispute, AI drafts dispute answers and invoice reminders for the seller to approve, and AI agents can request refunds over MCP.

Comment

Inspiration

Small sellers who ship abroad live with one constant question: where is my money right now? A payment can be captured, held, partly refunded, disputed or waiting on an invoice, and PayPal shows each of these on a different screen. Disputes hurt most: a buyer who just wanted an answer opens a claim, the seller has days to respond, and the response needs the right evidence in the right format. I wanted one place where a seller sees every payment's state at a glance, where buyers can ask before they dispute, and where AI does the drafting while the seller keeps the final say.

What it does

  • One clear line per order. Every order has a timeline built from real PayPal events: paid, shipped, refunded, disputed, settled. The line changes colour where the money's state changed.
  • Today. The seller sees only what needs them: a dispute to answer, a buyer question, an order to ship, an overdue invoice. Disputes waiting on PayPal or the buyer are folded away.
  • A private page for every buyer. After paying, the buyer gets a signed link (no account needed) to track the order, ask for a refund or report a missing parcel before opening a dispute.
  • AI dispute assistant. When a dispute arrives by webhook, the AI reads the facts Clearline holds (payment, tracking, dispute reason) and recommends fight, refund or offer, citing the facts it used. For a shipped order it prepares the tracking evidence, and the seller approves before anything goes to PayPal.
  • Seller rules for small cases. An opt-in auto-resolve policy refunds small, clear-cut requests instantly, within per-order and daily caps. Shipped orders always go to the seller.
  • Agents welcome. An MCP server lets a buyer's AI agent check an order and request a refund using the buyer's private link, and lets a merchant agent read the seller's queue (read-only, with a key the seller creates).
  • Invoices. Describe an invoice in a sentence and the AI fills the form; overdue invoices get a polite AI-drafted reminder sent through PayPal Invoicing.
  • Money in flight and Insights. An AG Grid dashboard shows every order and invoice by money state, and an AG Studio Insights page lets the seller ask questions in plain words and have the AI build charts.

How I built it

  • Backend: Python and FastAPI, calling PayPal's REST APIs directly: Orders v2 (create, capture, tracking), Payments v2 (full and partial refunds), Disputes (evidence, messages, offers), Invoicing v2 and webhook signature verification. Every POST carries a PayPal-Request-Id, so retries never double-charge or double-refund.
  • Checkout: PayPal JS SDK v6; the order is created and captured on the server at the server's own price.
  • Data: every PayPal event is stored as a timeline row in Postgres (Neon); the clear line, Today and the dashboard are all computed from those timelines.
  • AI: Gemini 3.5 Flash-Lite with Groq (gpt-oss-120b) as fallback. Strict JSON output, every cited fact checked, personal data stripped before anything is sent, no invented amounts, dates or emails. Money only moves on a seller's click or within the seller's own auto-resolve rules.
  • Agents: an MCP server (Streamable HTTP) with buyer tools scoped by the signed link and read-only merchant tools behind hashed API keys.
  • UI: a hand-built design system; AG Grid and AG Charts for the dashboard; AG Studio for Insights, with its AI running through Clearline's own backend.
  • Production: Render and Neon Postgres; Argon2id seller accounts with database sessions; a Content-Security-Policy and security headers on every page; GitHub Actions runs the tests on SQLite and Postgres plus a secret scan, and deploys only when everything is green.
  • Testing: 514 automated tests, plus a live end-to-end script that drives the real site and PayPal Sandbox: checkout, shipping, refunds, disputes, agent refunds, invoices and Insights. The demo video was filmed by the same tooling.

Challenges I ran into

  • Dispute rules the API doesn't spell out. PayPal's links sometimes offered actions that weren't allowed; messages only work at the inquiry stage, evidence only while PayPal waits for the seller, and at the chargeback stage only proof of delivery with a PDF was accepted. I ran controlled Sandbox experiments and built the flow around what PayPal actually accepts.
  • Webhooks arrive out of order and twice. An "updated" event can arrive before "created", and a new dispute says UNDER_REVIEW and then WAITING_FOR_SELLER_RESPONSE 30 seconds later. Clearline orders events by PayPal's own update time, ignores repeats, and asks the AI once per stage.
  • Free-tier AI limits. Gemini 3 needs its "thought signatures" returned on every tool call, and Groq's free tier allows 8,000 tokens a minute, so the Insights assistant keeps signatures server-side and trims its prompts.
  • The real client IP behind Cloudflare and Render for login rate limits, without letting a spoofed header win.

Accomplishments that I'm proud of

  • Every money flow works live in PayPal Sandbox: checkout, shipping, full and partial refunds, AI-drafted dispute evidence, invoices with reminders, and an AI agent getting an instant refund over MCP.
  • The AI never moves money on its own and never sees personal data; every fact it cites is checked.
  • It runs as a real production app: accounts, security headers, CI that blocks secrets, deploys only on green, health checks, and a live end-to-end test that can be rerun any time.

What I learned

  • Most payment pain is about state, not features: showing the seller exactly where each payment stands removes most of the anxiety.
  • The PayPal Sandbox is the real teacher; the docs describe the happy path, the Sandbox shows the rest.
  • AI is most useful when it drafts with cited facts and a human approves, especially where money is involved.

What's next for Clearline

  • Carrier tracking and delivery proof pulled in automatically, for stronger dispute evidence.
  • Multi-currency settlement views and more export paperwork for cross-border sellers.
  • Going live with production PayPal credentials for a few pilot sellers.

Built With

Share this project:

Updates

Submission history