-
-
FairHold makes milestone-based payments more transparent through AI assistance, human decisions, and accountable payment workflows.
-
A unified dashboard giving buyers and freelancers visibility into deals, milestones, progress, and payment status.
-
Every project starts with a clear agreement, defined responsibilities, and transparent payment terms.
-
Break projects into measurable milestones with allocated amounts, clear progress, and defined acceptance criteria.
-
Freelancers submit deliverables and supporting evidence against agreed milestone requirements.
-
Buyers review submitted evidence and make accountable, human-led milestone approval decisions.
-
PayPal Sandbox powers controlled payment operations through order creation, approval, authorization, capture, and void.
-
Google Gemini assists with structured milestone proposals and evidence summaries while keeping decisions under human control.
-
FairHold connects its application backend, PostgreSQL, Gemini AI, and PayPal Sandbox through clearly separated responsibilities.
-
From agreement to evidence review and payment execution, every milestone follows an accountable workflow.
Inspiration
Trust is one of the biggest challenges in freelance and milestone-based work.
A client wants confidence that the agreed work will be completed before releasing payment. A freelancer wants assurance that completed work will be reviewed fairly and payments won't be unnecessarily delayed. But when agreements, deliverables, revisions, approvals, and payments are scattered across conversations and disconnected tools, misunderstandings can quickly turn into disputes.
We wanted to build something that makes this process more structured, transparent, and accountable.
That idea became FairHold — a milestone-based payment coordination platform built around one belief: trust should be supported by clear agreements, verifiable evidence, accountable decisions, and predictable payment operations.
What it does
FairHold brings the agreement-to-payment journey into one structured workflow, connecting buyers and sellers through clearly defined milestones and evidence-based reviews.
Its key capabilities include:
- Structured agreements: Buyers and sellers can establish deal terms, define deliverables, and specify milestone acceptance criteria.
- Milestone management: Projects are divided into individual milestones with allocated amounts, progress states, and review stages.
- Evidence-based submissions: Sellers can submit completed work, descriptions, links, and supporting evidence against agreed requirements.
- AI-assisted insights: Google Gemini API integration supports structured milestone proposals and evidence-related advisory workflows. AI output remains a recommendation, never a financial decision.
- Human-controlled approvals: Buyers retain authority to review submissions, request revisions, accept completed work, and approve payment actions.
- PayPal Sandbox integration: A server-side payment adapter supports authorization, capture, partial capture, and void operations.
- Accountable activity history: Important workflow and payment events are recorded to support traceability and auditing.
FairHold is built around five principles:
AI proposes. Humans decide. Rules enforce. PayPal executes. The audit trail records.
How we built it
We built FairHold using a modern web architecture with an emphasis on payment correctness, separation of responsibilities, and predictable state management.
Application Layer
- Next.js and React power the application experience.
- TypeScript provides type safety and maintainable application logic.
- Tailwind CSS supports a consistent, responsive interface.
- PostgreSQL and SQL migrations provide the database schema and persistence foundation.
AI Layer
- Google Gemini API supports AI-assisted milestone and evidence-related advisory workflows.
- Structured output validation ensures AI responses conform to expected application schemas.
- Deterministic fallback behavior keeps workflows predictable when the AI service is unavailable or not configured.
- AI recommendations are isolated from critical business logic and payment execution.
Payment Layer
- PayPal Developer Platform and Sandbox provide the payment integration environment.
- Server-side OAuth 2.0 authentication handles provider API access.
- PayPal Checkout Orders and Payments Authorizations APIs support authorization, capture, and void operations.
- Idempotency safeguards help prevent duplicate payment operations.
- Amount validation and concurrency controls help protect against invalid or excessive captures.
- Webhook signature verification, event deduplication, and reconciliation safeguards support asynchronous payment-event handling.
One of our most important architectural decisions was separating AI recommendations from business rules and payment execution.
Gemini cannot independently approve milestones, modify payment amounts, authorize captures, or make financial decisions. Those actions remain governed by explicit application rules and authorized human decisions.
Demo disclosure: The public guided demonstration uses simulated payment actions. It does not move real money or make a live PayPal capture request.
Challenges we ran into
The biggest challenge wasn't simply integrating a payment provider. It was designing a workflow where financial operations remain predictable even when requests fail, arrive more than once, or complete asynchronously.
1. Payment State and Correctness
Authorization, capture, partial capture, and void operations have different financial consequences. We had to carefully model these transitions and ensure that invalid operations could not proceed through the normal workflow.
2. Duplicate Requests and Concurrency
Two simultaneous requests must not result in capturing more than the authorized amount. This required careful consideration of idempotency, amount validation, and concurrent state changes.
3. Asynchronous Webhooks
Payment-provider events can arrive after an operation begins, be delivered more than once, or require reconciliation. We designed verification and deduplication safeguards so that provider events serve as payment evidence rather than independent approval decisions.
4. Making AI Safe and Predictable
AI-generated recommendations can be incomplete or incorrect. We addressed this through structured output validation, deterministic fallback behavior, and strict boundaries that prevent AI from controlling financial operations.
5. Separating Responsibilities
Keeping the application experience, AI advisory layer, deterministic business rules, database state, and payment-provider operations separate required careful architectural decisions. This separation became one of FairHold's defining design principles.
Accomplishments that we're proud of
- Designed a complete milestone-based agreement and payment coordination workflow.
- Integrated an AI advisory layer without giving AI authority over financial decisions.
- Built a PayPal Sandbox payment adapter covering authorization, capture, partial capture, and void operations.
- Prioritized idempotency, amount validation, concurrency safeguards, and payment-state integrity.
- Established human approval as an explicit boundary between completed work and payment execution.
- Created a guided demonstration that communicates the complete product journey without pretending simulated payments are real transactions.
- Made financial correctness, transparency, and accountability central to the architecture rather than treating them as afterthoughts.
Our proudest accomplishment is the architecture behind FairHold: AI can make a workflow smarter, but financial authority must remain deterministic, transparent, and accountable.
What we learned
Building FairHold changed how we think about AI-powered financial applications.
We learned that integrating an AI model is only one part of building a useful AI product. The harder work is defining what the model is allowed to do, validating its output, handling failures, and ensuring that uncertain recommendations never become unauthorized financial decisions.
We also learned that payment integrations involve much more than successful API requests. Idempotency, concurrency, partial captures, asynchronous events, ambiguous outcomes, and reconciliation all matter when designing systems that may eventually handle real money.
Most importantly, we learned that responsible AI is not just about what a model can do. It is equally about what it must never be allowed to control.
With FairHold, we bring together four distinct responsibilities:
- AI assists.
- Humans decide.
- Deterministic rules enforce.
- PayPal handles payment operations.
An auditable activity history helps make the process traceable.
FairHold is our attempt to make milestone-based work more transparent, payment workflows more accountable, and trust something that can be supported by evidence rather than promises alone.
Explore FairHold
Built With
- ai
- fintech
- next.js
- node.js
- oauth
- payment
- paypal
- postgresql
- react
- rest
- tailwind
- typescript
- webhooks
