Fairshake

Hold the money with PayPal, let AI check the work line by line, and pay only for what was delivered.

Comment

Inspiration

I've done small freelance jobs on the side and I've also hired people for them. Both sides end up in the same bad spot. If the client pays first, they're hoping. If the freelancer works first, they're hoping. And when the job is 80% right, the conversation turns into "I'm not paying until it's perfect" versus "I did most of it, pay me."

Nobody wrote down what "done" meant, and the only two options at the end are pay everything or pay nothing.

While reading the PayPal docs I noticed authorizations can be captured partially, and final_capture releases the rest back to the buyer on its own. That's exactly the shape of a fair answer. The missing piece was deciding how much to capture without it becoming another argument. That's where AI actually fits.

What it does

Fairshake runs a small job through four steps:

  1. Agree. The client pastes a brief written the normal way. AI turns it into a short checklist where each item is worth a share of the budget. The client can edit anything.
  2. Hold. The client approves the payment with PayPal. It's an authorization, so nothing is charged yet, but the freelancer can see the money is really there. The checklist locks.
  3. Deliver. The freelancer pastes the work or a link. AI reads it and marks each item met, partial or missing, quoting the exact line from the delivery as evidence.
  4. Settle. The client sees the suggested split and can override any line. Overrides go into a shared history. On release, Fairshake captures the earned amount and PayPal releases the rest to the client. If nothing was delivered, the hold is voided.

There's also "ask for changes", which sends the unmet items back to the freelancer so they can resubmit against the same hold.

One rule I stuck to: the AI never picks the money. It only judges each item and must show evidence. The payout is simple math in code (weight × score), and the client confirms it.

How I built it

  • Backend: Node.js and Express, with a JSON file store so judges can run it with just npm install && npm start.
  • PayPal: Orders v2 with intent: AUTHORIZE and payee set to the freelancer's PayPal email, the JS SDK Buttons for approval, /authorize to place the hold, then Payments v2 /capture with a partial amount and final_capture: true, or /void when nothing was delivered. Every money call sends a PayPal-Request-Id so retries can't double capture.
  • AI: Gemini 2.5 Flash through its OpenAI-compatible endpoint, so it also works with Groq, OpenRouter, Ollama or OpenAI by changing env vars. Two prompts: brief → weighted checklist, and delivery → per-item verdicts with quotes.
  • Frontend: plain HTML, CSS and JavaScript. No build step. One page with a client view and a freelancer view.
  • Fallbacks: without PayPal keys it runs on a mock PayPal, and without an AI key it uses a basic keyword checker. Both show a clear banner, so nobody mistakes them for the real thing.

Challenges I ran into

  • Making the AI fair, not nice. Early prompts gave high marks to deliveries that talked about doing something without actually doing it. Requiring a quote from the delivery for every "met" fixed most of that.
  • Weights never add up. Models are bad at making numbers sum to 100. I gave up asking and normalise in code.
  • Who controls the checklist. If the client can edit it after funding, the goalposts can move. So it locks when the money is held. That one rule made the whole thing feel more trustworthy.
  • Authorization windows. PayPal holds are honoured for 3 days and valid for 29, which shaped what kind of jobs this fits today (small, quick ones) and what milestones need to look like later.

Accomplishments that I'm proud of

  • Partial capture with automatic release turned out to be a really clean way to express "you get paid for what you did."
  • The evidence quotes. When the client sees the exact line the AI is pointing at, it stops feeling like a black box.
  • Every override is visible to both people. Nobody can quietly change the outcome.

What I learned

  • PayPal's authorize and capture flow is much more flexible than the usual "Pay Now" button suggests.
  • AI is most useful here as a structured referee with receipts, not as a decision maker.
  • Small rules like locking the checklist matter as much as the tech.

What's next for Fairshake

  • Milestones: split bigger jobs into steps, each with its own hold.
  • Proper accounts for both sides instead of two links.
  • Connecting to PayPal disputes when the freelancer disagrees with the final call.
  • Reviewing images and PDFs with a vision model, for design work.

Testing instructions (for judges)

Repo README has full steps. Short version:

  1. git clone, npm install, cp .env.example .env
  2. Add PayPal sandbox client ID and secret, plus a free Gemini key
  3. npm start, open http://localhost:3000
  4. "Fill with an example" → draft → pay with a sandbox personal account → switch to Freelancer view → submit work → back to Client view → release

npm test runs the full lifecycle against the mock PayPal.

Share this project:

Updates

Submission history