-
-
Client Dashboard & Milestone Ledger
-
Freelancer Perspective Dashboard
-
AI Contract Builder — Chat Input
-
Gemini Contract Extraction & Acceptance Criteria
-
Milestone Funding & PayPal Checkout
-
Verified PayPal Funds in Milestone Ledger
-
Freelancer Work & Evidence Submission
-
AI Acceptance Gate — Criteria Audit Report
-
Client Decision & Payout Authorization
-
Exportable Evidence & Dispute Mediation Pack
Inspiration
The global gig economy is projected to exceed \$1.8 trillion, yet high-stakes freelance agreements still happen across informal chat channels—Slack threads, WhatsApp messages, Discord DMs, and Telegram groups.
This conversational deal-making causes an ongoing dilemma:
- Freelancers risk non-payment, endless unpaid scope creep, and arbitrary withholding if they deliver upfront.
- Clients risk lost capital and delayed projects if they pay upfront without guaranteed deliverables.
Traditional escrow platforms require cumbersome onboarding, take steep commission fees (often $10\% - 20\%$), and rely on slow, manual dispute desks that take weeks to review technical work. We asked: What if an intelligent AI agent could sit between conversational negotiations and financial settlements?
By combining Google Gemini for real-time contract synthesis and objective milestone auditing with the PayPal REST API for verified payments, we created ChatEscrow—an autonomous milestone payment protection workflow that turns casual chat agreements into verified, protected disbursements.
What it does
ChatEscrow manages the entire lifecycle of freelance project collaboration:
- Chat-to-Contract AI: Users paste raw chat transcripts into the AI Contract Builder. Powered by Google Gemini, the system extracts deliverables, milestones, deadlines, budgets, and clear, testable acceptance criteria.
- Mutual Dual-Approval Gateway: Both the Client and Freelancer must review and approve the exact same contract version before milestone funding or work begins.
- PayPal Milestone Funding & Verified Capture: Clients fund milestones server-side via the PayPal REST API (
/v2/checkout/ordersand verified/v2/checkout/orders/{id}/capture). The backend matches captured amounts directly to the milestone budget before recording them in the ledger. - Milestone AI Acceptance Gate: When the freelancer submits deliverables (code links, design URLs, docs), Gemini audits the submission against each agreed acceptance criterion: $$\text{Criterion Status} \in {\text{MET}, \text{PARTIALLY_MET}, \text{NOT_MET}}$$ along with confidence ratings $c \in [0.0, 1.0]$, specific evidence citations, and recommendations.
- Client Decision & Payout Release: The client reviews the objective AI findings to Accept Milestone, Request Revision (with specific, AI-guided feedback), or Flag Disagreement. Upon acceptance, the client authorizes payout release to the freelancer.
- Neutral Evidence & Dispute Pack: If an impasse occurs, ChatEscrow compiles a complete, tamper-evident audit bundle (contract terms, PayPal transaction hashes, submission links, and AI audit evaluations) ready for third-party mediation.
- Persona Switcher: Evaluators can instantly switch between Sarah Miller (Client) and Alex Carter (Freelancer) in the top navigation bar to test both perspectives in real time.
How we built it
We engineered ChatEscrow around a decoupled full-stack architecture built for financial integrity, idempotency, and verifiable AI outputs:
┌─────────────────────────────────────────────────────────────────┐
│ Frontend (React 19 + TypeScript) │
│ • Role Persona Switcher (Client / Freelancer) │
│ • Contract Draft Builder & Dual-Approval Gateway │
│ • PayPal Checkout Modal & Milestone Ledger │
│ • Deliverable Submission & AI Acceptance Audit UI │
│ • Exportable Dispute & Evidence Pack Generator │
└────────────────────────────────┬────────────────────────────────┘
│ REST APIs & Actuator Health
┌────────────────────────────────▼────────────────────────────────┐
│ Backend (Spring Boot 3.2.5 + Java 17) │
│ • Contract & Milestone State Machine │
│ • PaymentService (PayPal REST v2, Capture Verification) │
│ • Webhook Verification & Replay Protection Engine │
│ • AiService (Google Gemini 2.0 Flash + Offline Fallback) │
│ • Auditable Ledger & Tamper-Evident Event Store │
│ • In-Memory H2 DB (Seeded Demo Scenario) / PostgreSQL Ready │
└─────────────────────────────────────────────────────────────────┘
- Backend (Spring Boot 3.2.5 & Java 17):
- PayPal REST API Integration: Server-side order creation (
intent: CAPTURE), bearer token caching via OAuth 2.0 (/v1/oauth2/token), and strict capture verification. - Financial Precision: Checks captured amounts against expected milestone budgets: $$\Delta = |V_{\text{captured}} - V_{\text{expected}}| < 0.001$$
- Resilient Webhook Engine: Verifies PayPal webhook signatures and persists event IDs in an atomic table with unique constraints to reject duplicates and replay attacks.
- State Machines: Guards against invalid operations (e.g., refunding uncaptured funds or disputing milestones that have not yet started).
- PayPal REST API Integration: Server-side order creation (
- AI Integration (Google Gemini):
- Uses
gemini-2.0-flash(with automatic runtime fallback togemini-1.5-flash) for contract synthesis and milestone auditing. - Includes a deterministic offline extractor and evaluator so judges can test the full app without needing an API key.
- Uses
- Frontend (React 19, TypeScript 5.7, Vite 8, Tailwind CSS):
- Modular screen architecture with real-time persona switching.
- 100% clean typecheck (
tsc --noEmit && vite build) with zero compiler warnings.
- DevOps & Containers:
- Multi-stage Dockerfiles and
docker-compose.ymlwith Nginx SPA reverse-proxy and Actuator healthchecks.
- Multi-stage Dockerfiles and
Challenges we ran into
- Clarifying the Financial Boundary: Regulated escrow services require fiduciary trust licenses, whereas standard PayPal Checkout executes direct seller captures. To deliver safety within clear legal boundaries, we designed a milestone payment protection workflow: captured PayPal transactions fund an auditable internal milestone ledger, while payout releases are authorized upon milestone acceptance.
- Payment Idempotency & Webhook Race Conditions:
Handling network timeouts during checkout posed risks of duplicate captures. We solved this by treating
ORDER_ALREADY_CAPTUREDresponses on retries as state confirmations rather than errors, and by claiming webhook event IDs in the database before processing them. - Preventing AI Contract Hallucinations: Generative AI can introduce terms not agreed to in the original chat. We enforced a Human-in-the-Loop Dual-Approval Gateway where the AI draft remains strictly a proposal until both parties independently review and confirm the identical draft.
- Objective Deliverable Grading: Evaluating subjective deliverables against vague requirements like "make it modern" is prone to bias. We engineered structured prompts requiring Gemini to match submitted URLs and descriptions to individual contract criteria, cite specific proof, and assign numerical confidence scores.
Accomplishments that we're proud of
- 24 Comprehensive Automated Integration Tests: Complete test suite (
mvn test) covering order creation, capture verification, amount/currency mismatch guards, retry idempotency, webhook deduplication, mutual approvals, and dispute mediation. - Zero-Warning, Zero-Error Builds: Both the Java backend (clean build with
@Builder.Defaultannotations) and the React frontend compile with 0 warnings and 0 errors. - Zero-Config Evaluator Experience: Judges can launch the app and immediately test every feature using pre-seeded demo data, without needing sandbox accounts or live API keys.
- Exportable Evidence & Dispute Pack: A one-click audit artifact generator that creates a complete evidentiary record of the contract terms, payment receipts, deliverable URLs, and AI evaluations ready for third-party mediation.
What we learned
- PayPal Checkout v2 Lifecycle Nuances: Mastered server-side order orchestration, capture validation, timeout reconciliation, and webhook signature verification (
PAYPAL-TRANSMISSION-SIG,PAYPAL-CERT-URL). - Deterministic Schema Engineering: Learned how to prompt Google Gemini to consistently return structured, strongly-typed JSON for legal and financial audit workflows.
- Defensive Financial State Machines: Deepened our understanding of designing idempotent state machines that gracefully handle edge cases such as
UNKNOWNcapture states and network retries.
What's next for ChatEscrow — AI-Powered Milestone Payment Protection
- PayPal Marketplace / Multiparty Payouts: Implementing multi-party disbursement using PayPal Marketplace APIs to automatically distribute funds between freelancer, client, and platform fees upon milestone approval.
- Automated VCS & CI Integration: Connecting GitHub and GitLab webhooks to the AI Acceptance Gate to verify pull requests, commit histories, unit test pass rates, and build statuses directly.
- Decentralized Arbitration Export: Enabling one-click export of the Dispute & Evidence Pack to decentralized dispute resolution protocols (e.g., Kleros) and professional small-claims mediation platforms.
Built With
- ai-agents
- docker
- docker-compose
- fintech
- gemini-api
- google-gemini
- h2-database
- java
- junit5
- lucide-react
- maven
- nginx
- oauth2
- paypal
- postgresql
- rest-api
- smart-contracts
- spring-boot
- spring-data-jpa
- typescript
- webflux
- webhooks