Inspiration
Two people inspired Paylock, and they're on opposite sides of the same problem.
The first is a freelance designer who finished a logo, sent the files, and never heard from the client again. No invoice chase works when the other person simply stops replying. The second is a small business owner who paid a deposit to a developer who had a convincing portfolio, a friendly tone, and a reason why the payment had to happen "outside the platform, just this once." The portfolio was stolen. The deposit was gone.
Both of them did what everyone does online: they paid, or they worked, on trust. That is the real bug. Money moves before anyone has checked the work, and before anyone has checked the person. Every protection that exists today kicks in afterwards, when the money is already gone and the dispute process begins.
[CITE: one sourced figure on online purchase or payment fraud losses, e.g. the latest FTC Consumer Sentinel or FBI IC3 report.] [CITE: one sourced figure on freelancer late or non-payment, e.g. a Freelancers Union or Payoneer survey.]
We kept coming back to one question: what if the payment itself could wait for proof? Not a human escrow officer who takes three days and a percentage, but an agent that reads the agreement, checks the counterparty, verifies the delivered work, and only then tells PayPal to release the money. And what if that same agent could stop a payment before it starts, by noticing the signals a person under pressure misses: a two-day-old account, a payout email that changed ten minutes ago, a message asking to move the conversation somewhere else.
There was a second reason to build this now. AI agents are starting to spend money on people's behalf. An agent with a wallet and no judgment is exactly what a fraudster wants to meet. The guardrails that protect a human buyer are the same ones an autonomous buyer needs. We wanted to build both at once.
Pay for proof, not promises. That became Paylock.
What it does
Paylock is an AI escrow agent built on PayPal's sandbox. It sits between an agreement and a payment, and it makes the money wait until the work is proven.
A deal moves through six steps:
1. Describe the job. The buyer writes what they need in plain language. The Negotiator agent turns it into a structured contract: scope, price, deadline, and a checklist of acceptance criteria, each marked as automatically checkable, judgeable by AI, or needing a human. Ambiguities are flagged so the buyer can fix them before anything is locked.
2. Check the risk. Before any money is reserved, the Trust Guardian scores the deal. It combines hard signals from the platform (account age, completed and failed deals, dispute history, payout email changes, deal velocity, amounts split just under approval limits) with an AI reading of the messages for social-engineering patterns: urgency pressure, requests to pay off-platform, upfront "release fees", overpayment-and-refund schemes. It produces a score, a level, and a plain-language explanation. Low risk proceeds. Medium risk needs a human tap. High risk is blocked, and the buyer sees exactly why: "This seller's account is 2 days old, their payout email changed 10 minutes ago, and their message asks you to pay a deposit outside Paylock."
3. Lock the funds. The buyer approves with PayPal. Paylock creates the order with intent: AUTHORIZE, so the money is reserved but not taken. The seller sees that funds are locked before they start work.
4. Deliver. The seller submits the result: a URL, a repository, a file, or text.
5. Verify. The Verifier agent checks each acceptance criterion. For technical criteria it runs real checks (does the page load, does it respond at mobile and desktop widths, do the tests pass). For judgment criteria it reads the fenced deliverable and cites evidence. It outputs a per-criterion result, a confidence, a weighted score, and a decision: PASS, PARTIAL, or FAIL. Low-confidence calls go to the buyer for review instead of being guessed.
6. Settle. On PASS, Paylock captures the authorization and pays the seller through PayPal Payouts, instantly. On PARTIAL, it captures a proportional amount and the remainder is released back. On FAIL, it voids the authorization and the buyer keeps their money. If a seller never delivers, the deadline voids it automatically.
Every step lands on a live timeline that both parties see: each state change, each agent decision with its reasoning, and each PayPal event as it is confirmed by webhook. Buyers set a spend policy (max per deal, daily cap, approval threshold) that the platform enforces server-side, so neither a person under pressure nor an autonomous agent can overspend.
The human stays in charge. Every AI decision can be overridden, and every override is logged and visible to both sides.
How we built it
Architecture. A modular monolith: a Fastify API (Node 20, TypeScript), a Next.js 14 web app, and PostgreSQL via Prisma. Agents run in-process as modules with strict boundaries. Deals store their current state for fast reads; every transition is also appended to an event table that powers the timeline and the audit log.
PayPal. Orders v2 with AUTHORIZE intent, Payments v2 for authorize, capture (always with an explicit final_capture), void, and refund, Payouts v1 for seller payment, and Webhooks v1 verified against PayPal's signature endpoint from the raw request body. Buyer approval uses the JavaScript SDK v6 (createInstance, findEligibleMethods, createPayPalOneTimePaymentSession). Every money-moving call carries a PayPal-Request-Id tied to exactly one request body, and retries reuse it. The adapter uses plain fetch against the REST API; no deprecated SDKs.
AI. Three agents (Negotiator, Guardian, Verifier) behind one LlmClient interface, running at temperature 0 with JSON-schema structured outputs validated by Zod. We used Google's Gemini 2.5 Flash through its OpenAI-compatible endpoint. Every prompt passes through a PII redaction middleware first: names, emails, phone numbers and payment identifiers become stable tokens, and are restored only for display. Deliverable text, messages and tool results are fenced as untrusted data. Agents can only call read-only skills; settlement is deterministic code.
Money safety. A state machine with explicit transitions and guards (DRAFT through CONTRACTED, GUARDED, FUNDING, LOCKED, DELIVERED, VERIFYING, RELEASING, RELEASED, plus FLAGGED, AWAITING_APPROVAL, NEEDS_REVIEW, SETTLEMENT_ERROR, VOIDED and CANCELLED). Settlement runs in two database transactions around each PayPal call: the first records the decision, the policy approval and a pending payment record under a row lock; then PayPal is called; then the second records the result. A sweeper resumes anything interrupted using the same idempotency key, polls captures and payouts to completion, and voids expired holds. Webhooks only append events and never move a deal backwards; a reconciler reads PayPal's current state and only moves forward.
Development. We built with the PayPal AI Toolkit loaded into our coding assistant. Its best-practices skill and pre-edit hook pushed us to v6, to explicit final_capture, to raw-body webhook verification, and away from deprecated endpoints. /paypal:explain-error resolved every sandbox error we hit, and each fix is logged in docs/pitfalls.md. We probed PayPal's sandbox MCP server from the app (it connected and listed 46 tools), but tool calls returned a server-side error during the hackathon, so MCP enrichment is off and we say so rather than claim it.
Testing. 655 unit and integration tests, Playwright end-to-end runs of the happy, scam and fail paths against the real sandbox, an axe accessibility suite (0 serious or critical issues), a fresh-clone test in a clean node:20 container, and an agent evaluation suite of labelled cases replayed from recorded fixtures.
Hosting. Render for the API and web app, managed Postgres, GitHub Actions for CI (lint, typecheck, tests with a Postgres service, build, secret scanning).
Challenges we ran into
Escrow without an escrow product. PayPal has no native escrow for this use case. We built it from authorize-then-capture. The sandbox taught us the authorization expires 29 days after creation, with a shorter guaranteed honor period, so we cap deal deadlines at 72 hours and designed milestones for anything longer.
Never move money twice. The scary paths are all between capture, payout and refund. We learned in the sandbox that reusing a PayPal-Request-Id with a different amount returns the original capture while echoing the wrong amount, so every capture is re-read with a GET and compared on amount and status. A reused Payouts sender_batch_id is rejected outright with no link to the original, so re-sends use a new batch id and we recover the real batch from the webhook. Each decision claims its state in the database before PayPal is called.
Webhooks lie about order. VOIDED arrived before CREATED for the same authorization. ORDER.APPROVED arrived three times with different event ids. Simulator events never pass signature verification. We made webhooks append-only, deduplicated by event id, and moved all state decisions to a reconciler that reads PayPal directly.
Payment review almost broke the demo. Halfway through Day 1, every capture started returning PENDING_REVIEW. The cause was a sandbox account setting, not code. It forced us to build capture polling into the sweeper and a "Confirming with PayPal" state into the UI, which turned out to be the right design anyway.
AI that can't be talked into paying. A deliverable is attacker-controlled text. We fence it, we forbid agents from touching write tools, we validate every output against a schema, and we route low confidence to a human. Our eval includes an injection case where the deliverable tries to force a pass.
Free-tier LLM quotas. We lost most of a day to daily request caps on free models, and one model simply couldn't produce valid JSON under schema mode. We switched to Gemini 2.5 Flash, paced the recording of fixtures, and made the hosted demo run entirely from recorded agent responses, so a rate limit can never break a judge's run.
Telling the truth on screen. We adopted a rule: never show "Released" before PayPal confirms it, never label a person, only describe signals. Copy says "risk signals" and "funds reserved, released, returned". A test fails the build if the word "scammer" appears anywhere in the UI.
Accomplishments that we're proud of
- The whole flow moves real sandbox money, end to end. Order, authorization, capture confirmed by GET, payout batch confirmed by polling, deal released. The failure path voids the authorization and returns the funds. Both are exercised by automated tests against the live sandbox, and the PayPal ids are in the repository.
- The AI is the decision, not decoration. On our labelled evaluation set, the agents reached the threshold we set before building (at least 9 of 10 outcomes correct), with every scam persona blocked and every bad deliverable failed. Rules alone cannot read a message that says "pay me outside the platform"; the Guardian can, and it explains why.
- Guardrails you can test. A static test enforces that only the settlement module can import capture and payout. Another asserts the test-only card funding route cannot exist in production. A provider spy proves no PII reaches the model. Policy limits are enforced server-side and re-checked inside the authorize transaction.
- A fresh clone runs. A judge can clone the repository and follow the README in a clean container. We know because we did it, found a missing
jqprerequisite, and fixed it. - Accessible by default. WCAG 2.1 AA, keyboard navigation, live-region announcements for timeline and risk changes, 0 serious or critical axe findings on every screen.
What we learned
Verify the work, not just the payment. Fraud scoring protects the payer. Verifying the deliverable protects both sides and removes the reason to argue later. The acceptance-criteria contract was the single most useful artifact in the system.
Prevention beats protection. Showing a risk explanation before the money is reserved changes behavior. A person under pressure will still click; a person shown "this account is two days old and the payout email just changed" usually won't.
Agents decide, the platform enforces. We never let a model call a money-moving function. The model produces a structured decision; deterministic code, policy and idempotency do the rest. This made the system both safer and far easier to test.
The sandbox is a teacher. Every surprising behavior we hit (idempotency echoes, payout batch rejection, out-of-order webhooks, pending review) became a test and a documented pitfall. Reading documentation was not enough; running real transactions on Day 1 saved the project.
Determinism is a feature. Recording agent responses as fixtures meant the demo runs identically every time and the evaluation is reproducible. It also made us honest: the hosted demo says plainly that agents replay recorded decisions.
What's next for PayLock
Milestones. Long jobs split into authorizations per milestone, each verified and released on its own, inside the honor period.
A larger, published evaluation. More labelled cases, a rules-only baseline alongside rules-plus-AI, and false-positive rates reported honestly. We want judges and users to see where the Guardian is wrong, not just where it is right.
Agent-to-agent deals. The API and policy engine already support an autonomous buyer agent operating under a spend policy. The next step is a public tool definition so agent frameworks can use Paylock as their default way to pay for work, with the same risk gating and verification a human gets.
Dispute evidence export. When a deal fails or is contested, the Verifier's per-criterion evidence and the full timeline become a ready-made dispute packet.
Trust that travels. Today's trust profile is per-platform. We want a privacy-preserving reputation that follows a seller across marketplaces, built from verified outcomes rather than star ratings.
Toward a native setting. Everything here runs on PayPal's public APIs: authorize and hold, void, capture, Payouts, webhooks. The natural home for Paylock is not another app but an option on a PayPal payment: "hold this until the work is verified." We would love to work with PayPal on that.
Limitations we know about. This is a sandbox prototype, not a licensed escrow service. Authorizations expire, so deals are time-boxed. The hosted demo replays recorded agent decisions for reliability. MCP enrichment is disabled until PayPal's sandbox server accepts tool calls. Risk signals are behavior-based and can be wrong, which is why a human can always override, and every override is logged.
Built With
- 13.
- ai-agents
- and
- backend
- frontend
- gemini
- github-actions
- google-ai-studio
- infra
- next.js
- node.js
- paypal-ai-toolkit
- paypal-javascript-sdk
- paypal-orders-api
- paypal-payouts
- paypal-sandbox
- paypal-webhooks
- postgresql
- prisma
- quality
- react
- render
- tailwind-css
- typescript
- zod
