Pay for the work that is done, not the work that is promised.

RealPay is milestone payments for a job between two people who do not trust each other yet. Each milestone is a PayPal authorization: the money is proven to be there, but nobody has it. It is only captured and paid out when an AI inspector and the homeowner accept the proof of work.

Try it now, no account needed: open the live demo and choose a side. A switch at the top of every job lets you jump between the client and the professional in one click. I pay for the work opens a sample job where you pay the milestones in order with the sandbox test card. I do the work lets you set up your own job in a minute and gives you one link to send to your client. Sample proofs to upload, including two cheating attempts, are in demo/proofs. The demo is a free instance, so the first load can take about a minute.

Inspiration

A contractor took €2,975 in cash, upfront, for a home renovation. A day later there was a pipe sticking out of the wall, a cracked shower tray, and a phone nobody answered. In the end there was a police report and two losers: the homeowner lost the money, and the contractor ended up facing a criminal complaint.

Neither of the usual options works. Paying everything upfront protects the contractor, and paying everything at the end protects the client. Banks solved this decades ago for construction loans: they release the money in stages, after an inspector signs off each one. We wanted that same discipline for a €3,000 renovation, without a bank, an escrow agent or a human inspector on every visit.

What it does

RealPay is for homeowners and small contractors who do not know each other yet: the homeowner will not pay everything upfront, and the contractor will not start without knowing the money is there. Each side gets what it was missing:

  • The homeowner never pays for work that is not there. Money on hold is still theirs, and cancelling voids it.
  • The contractor sees the money is there before starting, does not finance the materials, and gets every agreed extra paid.
  • Both have the same record if things go wrong, instead of one word against the other.

It starts with the professional, who sets up the job in about a minute: a 2 or 3 milestone starting point, with every price, deadline and "done when" checklist editable. RealPay returns one link to send to the client. The client opens it and sees the total, the milestones and a single bar: blue for what has been paid, orange for what is on hold. Milestones are paid in order, and every release tells both sides how much of the job is completed.

Each milestone is one PayPal order with intent: AUTHORIZE:

  • Materials are captured right away and paid to the supplier, so work can start. The contractor never holds the homeowner's materials money.
  • Labour stays authorized on the homeowner's PayPal: it is on hold, not charged.
  • When the work is done, the contractor uploads a photo or a certificate. The homeowner sees that same file on the milestone, next to the AI's verdict, and the proof goes through three layers:
    1. Free, deterministic prechecks: file type, duplicate hash, location, capture date and hidden instructions in the note.
    2. An AI vision inspector that scores the proof against the milestone's written checklist.
    3. A release policy in plain, tested code. It pays without a person only when the checklist is met, confidence is 0.8 or more, no flag is raised, no dispute is open and at most €650 is on hold. Anything else waits for the homeowner, and so does every job that a professional sets up by hand: only the built-in templates can release without a person.
  • On release, PayPal captures the labour and pays the contractor, minus a 5% retention kept for final fixes.
  • Cancel instead, and the hold is voided. Nothing was ever charged.

Real renovations change along the way, so the professional can propose an extra (change order) with its price, because whoever does the work prices it. Nothing is added until the client agrees on the page; then the extra becomes its own milestone, which the AI never releases alone.

If a dispute is opened, every release freezes. Every decision is written with its reason to a hash-chained ledger that both sides can export as an evidence pack.

How we built it

PayPal moves the money, the AI reads the proof, and plain code decides. The AI never calls PayPal. It is an AI agent that can release a payment by itself, but only inside limits written in code.

  • Payments: PayPal Orders v2 (authorize, capture, void, reauthorize), Payouts, Disputes, webhook signature verification, and the PayPal and Pay Later buttons from JS SDK v6. The demo adds a sandbox test card, so judges can fund a milestone without a PayPal login.
  • Server: TypeScript (ESM) on Express 5 with @paypal/paypal-server-sdk. zod handles input, SQLite (better-sqlite3) is the store, and helmet CSP plus rate limits guard the edges. The layout and conventions follow PayPal's public integration samples.
  • AI: a vision model (Gemini, falling back to OpenRouter, both on free tiers) returns a strict JSON verdict validated with zod. There is a daily cap per server and per project. When the cap is hit, or every provider is down, the proof goes to manual review.
  • Safety by design:
    • every PayPal call carries a deterministic PayPal-Request-Id, so a retry can never pay twice;
    • webhooks are verified on the exact bytes PayPal sent;
    • access works through secret links, with only their SHA-256 stored;
    • the server refuses to start with live credentials.
  • Quality: 255 vitest tests covering domain, policy, prechecks, AI, ledger and HTTP; eslint, tsc and prettier; and CI on Node 20 and 24 with a Docker smoke test. The API is documented in OpenAPI with a Postman collection.
  • Review loop: five rounds of read-only reviews before submission, from a jury critic, PayPal-style UX/UI, a PayPal integration expert, a senior full-stack engineer, a security engineer and a payments/finance specialist. Each finding was fixed in its own commit.

Tools

  • PayPal: Orders v2, Payouts, Disputes, Webhooks, JS SDK v6 and @paypal/paypal-server-sdk, all against the sandbox. No real money moves.
  • AI in the product: Google Gemini (vision), with OpenRouter as a fallback, both on free tiers.
  • Hosting: Render (free web service, deployed from the repo's render.yaml Blueprint).
  • AI used to build it: the code, tests and docs were written with Claude Code as a pair programmer and reviewed by a human. The story stills in the video are AI-generated illustrations and the narration is a synthetic voice; the app footage is a real screen capture against the PayPal sandbox.

RealPay is a new project, started for this hackathon: the first commit is from 10 November 2026.

Challenges we ran into

  • Multi-party orders with AUTHORIZE are not supported in sandbox for our flow (422 UNSUPPORTED_INTENT). We redesigned around one authorization per milestone, with a partial capture for materials and Payouts to the payees. The production path is written down: PayPal Multiparty, capturing straight to each seller.
  • Authorizations do not live forever. The honor period is 3 days and the authorization lasts 29 days, with one reauthorization for wallets only. The UI warns 4 days before expiry. An expired hold is never captured; the homeowner is told they were not charged.
  • Prompt injection through the proof itself. Attacks can come through the note, through text inside the photo, or through a change-order description written to read like instructions. We answered with layered defences: hard flags, a checklist fenced inside the prompt, and no auto-release for extras.
  • Making the AI a gate, not a judge. The model only scores. A pure, fully tested function decides, and money never moves on the model's word alone above the cap.

Accomplishments that we're proud of

  • An AI that is allowed to say "I'm not sure" and sends those cases to a human, instead of guessing with someone's money.
  • Two sides, one link: the professional sets the job up, the client opens a link, and neither needs an account or a manual.
  • One engine, many niches: a niche is a JSON template. Two ship today (home renovation, and a first booking with an unknown rental host), and any other job can be set up by hand from an editable preset.
  • Every unhappy path we could think of is handled and tested, from a declined card to a forged webhook. They are listed in the README.

What we learned

  • With AUTHORIZE, the money stays the buyer's until the moment it is earned. That is the right default for paying for work.
  • With AI on a payment path, the cheap deterministic checks catch the most. The model goes after them, and a person after the model.
  • Saying the limits out loud builds more trust than hiding them, which is why the README has a "Path to production" section and a list of known limits.

What's next for RealPay

  • PayPal Multiparty onboarding for contractors and suppliers, capturing straight to them, with the retention as a delayed disbursement.
  • More templates: freelance software milestones, event suppliers, small construction.
  • Live location capture at upload time. Today the check reads the photo's EXIF GPS against a 500 m radius around the site, which can be edited.
  • A mobile capture flow for contractors.

Disclaimers

RealPay is not PayPal Buyer Protection and does not replace it. It is an independent hackathon project, built on PayPal's sandbox, and is not affiliated with or endorsed by PayPal.

Built With

Share this project:

Updates

Submission history