The problem: work is a gradient, payments are binary

Every payment product treats a job as one of two states: delivered, or not delivered. Real work is never that clean.

A kitchen backsplash can be level, grouted at exactly 3 mm, and still have a chipped outlet cutout and no receipt for the materials. What is that job worth? Not 100% and not 0%.

The two existing options both punish someone for that gap. Pay up front and the buyer carries all the risk. Pay on completion and the seller carries it, which is why 85% of freelancers report being paid late (Remote, 2025) and why US small businesses carry unpaid invoices averaging roughly $17,500 (Intuit QuickBooks, 2025).

Milestone escrow is the usual answer, but it does not solve this. A milestone is still binary, it just makes the wrong unit bigger: "Phase 1 complete" is either true or it is not. Nothing in the stack can express 78% of this was actually delivered.

What Proven does

Proven makes the unit of payment the clause, not the job.

  1. Agree. A messy text message is drafted into 4-6 clauses. Each clause has an observable requirement, the evidence that would prove it, and a weight. Both parties accept the same definition of done before work begins.
  2. Prove. The seller attaches photos, receipts, or documents. Each file is SHA-256 hashed and bound to exactly one clause.
  3. Settle. A vision-capable model judges each clause and proposes a fraction between 0 and 1, with a confidence score and the filename it relied on. Deterministic server code turns those fractions into money. PayPal captures the proven amount and voids the rest, immediately.

The design rule that makes it safe: the model never sees dollars. It emits fractions and confidence only. One module (server/money.ts) is allowed to multiply by the contract total, and it works in integer cents.

Where PayPal is load-bearing

Proven is not a payments app with an AI wrapper. The product only exists because PayPal authorizations support this specific sequence:

Step PayPal primitive Why it matters
Reserve POST /v2/checkout/orders with intent: AUTHORIZE Holds the full amount without charging it
Approve POST /v2/checkout/orders/{id}/authorize Returns an authorization valid for ~29 days
Pay the proven share POST /v2/payments/authorizations/{id}/capture Charges only the adjudicated amount
Release the rest POST /v2/payments/authorizations/{id}/void Returns the money now, not in a month
Verify GET /v2/payments/authorizations/{id} The receipt shows PayPal's state, not ours

The subtle decision: final_capture is deliberately omitted from the capture call. Setting it to true closes the authorization and leaves the uncaptured remainder sitting in the buyer's hold for weeks. A partial capture followed by an explicit void is what actually returns the money the seller did not earn.

The proof it works

A real sandbox settlement from the application, re-read from PayPal's API:

  • Authorization 53031775H3888563X for $5,000.00, status CREATED to VOIDED
  • Partial capture 30F03817HJ137835C for $4,000.00, status COMPLETED, final_capture: false
  • $1,000.00 voided two seconds later, releasing the remainder immediately
  • 3 of 5 clauses proven, 2 missing, 80% released, confidence 0.876
  • released + voided = contract total, exactly

The full record is in docs/paypal-proof.txt. Every id in it came back from PayPal; nothing is mocked or typed by hand.

How I built it

  • Server: Node, Express, TypeScript, Zod for every input, a JSON file store with atomic writes. The PayPal REST API is called directly with fetch; no SDK, so every field is visible.
  • Domain layer: server/service.ts is the only place that knows the state machine (DRAFT to AGREED to FUNDED to EVIDENCE to ADJUDICATED to SETTLED) and the guards. Both the browser API and the agent API call the same six functions, so settlement cannot diverge based on who drove it.
  • Adjudication: any OpenAI-compatible endpoint. The model returns structured JSON validated by Zod: per-clause status, confidence, cited evidence, explanation, and proposedFraction.
  • Client: React 18, Vite, plain CSS, AG Grid for the ledger (lazy-loaded so the landing path stays small). No UI framework, no component library.
  • Agent surface: /api/agent exposes nine tool-shaped endpoints with an ordered nextActions array on every response, so an agent never has to guess what to do next. OpenAPI 3.1 contract at /api/openapi.json.
  • Validation: npm run verify runs 19 checks with no credentials and no network. It spawns the real server on a throwaway port and data directory, tests the settlement arithmetic at its source, then drives the whole state machine over HTTP on both surfaces. The same three commands run in CI on every push.

Challenges I ran into

Currency and payee are bound to the API app. USD checkout failed with UNSUPPORTED_PAYEE_CURRENCY because the sandbox app was linked to a non-US business account. The payee comes from the client ID, not from the order, so the fix was to create the US business account first and then create the app against it. This is documented in the README so nobody else loses an hour to it.

Partial capture is an account setting, not a code path. The capture call is correct long before the account will accept it.

A business account cannot pay itself. Sandbox checkout kept failing until I signed in as the buyer's personal account rather than the merchant.

Making the model unable to lie about evidence. Three guards, all server-side: a clause with no attached evidence is forced to missing with a fraction of 0 no matter what the model says; any cited filename is filtered against the real evidence list, so it cannot invent a file; and every fraction is clamped to 0..1 before arithmetic.

Rounding. Weights are normalised on ingest so they always sum to 1.000, and settlement is computed in integer cents with the remainder assigned to the void. released + voided equals the contract total for every case in the test suite, including totals that do not divide evenly.

Confidence has to be a gate, not a number in a UI. If overall confidence drops below 0.75, or any single clause below 0.6, settlement returns 409 REVIEW_REQUIRED and refuses to move money until a human acknowledges.

What I learned

The hard part of AI adjudication is not the model. It is deciding what the model is allowed to decide. Once the model only judges evidence against a clause the parties already agreed to, and the money is computed by code that has never seen a prompt, the system becomes auditable. The AI is doing the part only AI can do, interpretation, and none of the part software should never delegate, arithmetic.

The second lesson is that the interesting PayPal primitive here is the void, not the capture. Capturing part of an authorization is easy to describe and hard to make feel fair. Returning the remainder immediately is what makes the buyer whole, and it is the difference between "escrow" and "settlement".

What's next

  • Payouts and split settlement to multiple contributors on one agreement.
  • Postgres and signed webhooks; the JSON store is deliberately a demo shape.
  • A dispute path: a human reviewing verdicts and re-adjudicating with more evidence.
  • Reputation derived from real verdicts rather than star ratings.
  • A licensed escrow partner, because this is a settlement mechanism, not a regulated escrow service.

How AI is used, and what it is not allowed to do

  • In the product: clause drafting and evidence adjudication via an OpenAI-compatible endpoint. A vision model inspects attached images; without a key the app runs a deterministic template that is labelled heuristic-fallback in the UI, the ledger, the event log, and the proof file. It is never presented as model output.
  • Not allowed: producing dollar amounts, citing evidence that does not exist, or overriding the deterministic rules in server/money.ts.
  • In the build: I used AI assistance for implementation and documentation. The design decisions, the PayPal integration, the failure modes above, and the settlement proof came from running the thing against the sandbox and fixing what broke.

Limitations, stated plainly

PayPal sandbox only; no real money moves. Not a licensed escrow provider and not legal advice. Single JSON-file store, so no concurrent writers. No identity layer: two party buttons stand in for signed in users, and the agent API uses one shared bearer token. Webhook signatures are not verified. The authorization window is real (~29 days), so fund and settle in the same session.

Try it in sixty seconds

npm install npm run verify # 19 checks, no credentials, no network

The repository is public and MIT licensed: https://github.com/loki-msk/proven

Built With

  • ag-grid
  • agentic-commerce
  • ai-agents
  • authorization
  • escrow
  • express.js
  • fintech
  • llm
  • node.js
  • openai-compatible
  • openapi
  • partial-capture
  • paypal
  • paypal-rest-api
  • paypal-sandbox
  • react
  • rest-api
  • typescript
  • vision-model
  • vite
  • void
  • zod
Share this project:

Updates

Submission history