Inspiration

I spent 2 weeks perfecting a website for an allegedly Australian company who approached me on LinkedIn looking for a web designer and developer. In pre-AI web development, this was hard work for a newbie freelance web developer and I was proud of the website I had built. However, I never heard back from the client or got paid the pre-agreed amount. Unfortunately, this is not an incident that is unique to me. Freelancing runs on a trust gap that goes both ways. Freelancers who deliver first risk non-payment, endless revisions, or being ghosted. Clients who pay up front risk getting poor work or none at all. Marketplaces solve this inside their walls and charge a good chunk of the payment as platform fee, but most real freelance work happens outside them: direct clients, agency work, referrals, and cross-border deals.

I asked: what if payment could be tied to proof of delivery, with an AI referee that shows its evidence instead of asking anyone to trust it?

What it does

Vouch is a safe AI platform for freelancers and clients, built on PayPal. It makes sure freelancers get paid for good work and clients only pay for what they were promised.

  1. Agree on the job. The freelancer describes the work in plain language. Vouch's AI turns it into a clear brief: milestones, prices, and acceptance criteria that can be checked. The client can ask for changes in plain words, and the AI turns them into exact edits with a "what changed" list. Money can only be held once both sides accept the same version.
  2. Client pays, money is held. The client opens a private link (no account needed) and pays through PayPal. The payment is authorized, not captured, so the money is reserved but not yet sent.
  3. Freelancer delivers. They submit a live website link and, optionally, a GitHub repository.
  4. AI referee checks the work. Vouch loads the site in a real browser at phone and desktop size and runs measured checks: does it load over HTTPS, does it fit a phone screen, do images have alt text, does it run without JavaScript errors, what does Google Lighthouse score it, does the repo have new commits and passing CI. AI judges only what rules can't measure, and every "yes" must quote the page or cite the file and lines in the code.
  5. Money is released by clear rules. Good work gets full payment. Partly done work gets partial payment plus a list of fixes. The client has a review window to approve, or dispute once for an AI re-check and then decide. If they stay silent, the agreed rules apply automatically.
  6. Everything is on the record. A live ledger shows every step, with PayPal's transaction ids, and every PayPal webhook is verified with PayPal before it counts.

Payment follows the share of criteria that passed. With $A$ the milestone amount and $s$ the passed weight divided by the total weight:

$$ \text{release} = \begin{cases} A & \text{if } s \ge 0.9 \ A \cdot s & \text{if } 0.5 \le s < 0.9 \ 0 & \text{if } s < 0.5 \end{cases} $$

If a required criterion fails, nothing is released for that milestone. If the AI is unsure, or the delivery tries to manipulate the AI, a person decides.

How I built it

  • PayPal Orders v2: one order per job with intent: AUTHORIZE, then authorize. After authorizing, the held amount must match the agreed total to the cent, or the hold is voided at once.
  • PayPal Payments v2: many partial captures (final_capture: false) against one authorization, one per milestone release; one reauthorization after PayPal's 3-day honor period; and a void that returns the unused hold to the client. Every write carries a deterministic PayPal-Request-Id, saved before the call, so a retry or a double click can never pay twice.
  • PayPal Webhooks: checkouts, authorizations, captures, voids and refunds, each verified with verify-webhook-signature and recorded exactly once. The PayPal JavaScript SDK buttons handle the client's checkout.
  • APIMatic Context Plugin for PayPal: Installed it as skills for my coding agent, giving it accurate, version-aware context for the PayPal Server SDK (@paypal/paypal-server-sdk 2.5.0). It caught things the SDK's types don't show: the client has no timeout by default (it waits forever, so I set 15 seconds), retries are off unless two separate settings are both set (I turned them on, which is safe because every write has a request id), any logging config prints every request and response (so I removed it), and error details live in body, not result. Reading errors correctly is how I found PayPal's REAUTHORIZATION_TOO_SOON rule, which shaped the whole money model.
  • AI (Google Gemini, with Groq as a fallback): drafts the brief, proposes edits, and judges the subjective criteria through schema-validated structured output. Both run on free tiers, with answers cached. The AI never calls PayPal. It only proposes, and a tested policy function decides.
  • The referee: 20 measured checks, pages rendered in Kernel cloud browsers, Lighthouse scores via Google PageSpeed Insights, and public repositories read through the GitHub API at a pinned commit.
  • Next.js 16 and TypeScript for the app, Neon Postgres with Drizzle for data, Vercel for hosting, and a GitHub Actions scheduler that settles review windows every 10 minutes even when nobody is looking.
  • Testing: 223 unit tests, AI evals on fixed cases, an end-to-end walk-through with real PayPal sandbox payments, and a held-out benchmark for the referee.

Design principle: the AI proposes, a deterministic policy decides, and a human can always override.

Challenges I ran into

  • Authorization lifetime: a PayPal hold lasts 29 days, but captures are only guaranteed in the first 3. PayPal's docs say you can reauthorize many times; the sandbox said 422 REAUTHORIZATION_TOO_SOON: only allowed once from Day 4 to Day 29. I designed around the real API: one reauthorization after day 3, jobs capped at 25 days, and everything settled by the agreed rules a day before the hold ends.
  • Paying the freelancer directly: I first made the freelancer the payee, and partial captures landed straight in their PayPal account. But voiding the unused hold returned 403 PERMISSION_DENIED, because acting on a merchant's behalf needs PayPal partner onboarding. Without the void, a client could never get unused money back, so this build has the platform receive captures and tracks each freelancer's earnings in the ledger. Direct payouts are the production path.
  • Prompt injection: a freelancer's page can contain text that tries to instruct the AI grader. Code scans comments, hidden elements, attributes and visible text for instructions aimed at an AI, strips hidden text before the AI reads the page, and sends any hit to a person. Required measured checks can't be overridden by anything the AI says.
  • SSRF: Vouch fetches URLs that strangers submit, so it resolves DNS itself, blocks private, loopback and cloud-metadata addresses, re-checks every redirect, and caps time and response size.
  • Making AI judgments fair: criteria come from a library of measurable checks plus a few judged questions. The AI's quotes are checked against the real page or code, and a made-up quote or low confidence sends the decision to a person, so verdicts come with evidence, not vibes.
  • Web apps that looked empty: My first referee read raw HTML, so a working React app "had no heading", because its content is built by JavaScript. I moved to judging every delivery in a real browser, the way a visitor sees it. That same change caught a bug in my own "good" demo site: two images made the page wider than a phone screen.
  • Building from Pakistan: PayPal doesn't operate in Pakistan, so the whole project was built and tested on PayPal's sandbox, following the hackathon's guidance.

Accomplishments I am proud of

  • A full authorize, partial capture, reauthorize, void and release flow working end to end in the PayPal sandbox, with no way to pay twice or release more than the client authorized.
  • An evaluation card that shows why money moved, not just that it did.
  • A referee tested on 25 real websites and repositories it had never seen, each labelled by a person beforehand: no payment released that shouldn't have been.
  • Guardrails that survive a hostile submission in the demo.

What I learned

Agentic commerce is mostly about guardrails. The hard part isn't getting an AI to decide; it's making sure it can only decide within limits you can explain, test, and audit. I also learned how much faster integration goes when the coding agent has accurate API context, and that the sandbox is the final word: twice, the live API behaved differently from the docs, and testing early is what let me design around it.

What's next for Vouch

  • Real payouts straight to freelancers through PayPal Multiparty, which I already proved works for captures in the sandbox
  • More deliverable types (design files, documents, and code whose test suites the referee runs itself)
  • A neutral dispute-arbitration step
  • Support for more currencies and direct integration with the chat tools freelancers already use

Everything runs in the PayPal sandbox, with no real money.

Built With

Share this project:

Updates

Submission history