FairPay AI
Inspiration
Freelancing depends on trust, but things don't always go as planned. Clients and freelancers often disagree about whether the work is complete, whether it meets the original requirements, and when the payment should be released.
We noticed that many of these problems start with unclear expectations. A client might expect something different from what the freelancer understood, leading to repeated revisions, delayed payments, and unnecessary arguments.
We wanted to build a platform where both sides could agree on clear requirements before the work begins and use actual evidence to check whether those requirements have been met.
That's where FairPay AI came in. Our goal was to make freelance work more transparent and fair without taking the final decision away from the client.
What it does
FairPay AI helps clients and freelancers manage projects through clear milestones and evidence-based verification.
Here's how it works:
- Create a project: The client creates a project, defines milestones, and sets measurable acceptance criteria with the freelancer.
- Agree on requirements: Both parties review and agree on what needs to be delivered before the work starts.
- Submit work: Once the freelancer finishes a milestone, they submit their work and provide a public preview link as evidence.
- AI verification: Our system uses a read-only cloud browser to inspect the submitted work. Gemini analyses the collected observations and classifies each criterion as completed, missing, or unverified.
- Get improvement suggestions: If something is missing or cannot be verified, AI provides specific suggestions to help the freelancer improve the submission.
- Client approval: The client reviews the verification report and makes the final decision. AI never approves or rejects work on its own.
- Payment through PayPal: Once the client approves the milestone, the payment is processed through PayPal.
The main idea is to replace unclear discussions about completed work with agreed requirements and supporting evidence.
How we built it
We built FairPay AI using a full-stack architecture with AI-powered verification and payment integration.
Technology Stack:
- Frontend: React, Vite, TypeScript
- Backend: Node.js, Express.js
- Database: MongoDB, Mongoose
- AI: Google Gemini
- Browser Verification: Kernel
- Payment Integration: PayPal Orders API v2
Some important parts of our implementation:
Requirement Traceability: Every acceptance criterion gets a unique ID, allowing us to connect requirements with submissions, verification reports, and payment records.
Browser-Based Verification: Kernel opens the freelancer's public project preview in a read-only browser, captures desktop and mobile screenshots, and collects page observations. Gemini uses this information to evaluate individual criteria.
Structured AI Responses: We use Zod to validate Gemini's responses and maintain consistent verification results. Each criterion is classified as completed, missing, or unverified.
Revision Suggestions: A second Gemini call uses the verification findings to generate practical suggestions for fixing incomplete requirements.
Payment Security: Payment amounts and currencies are fetched from the database. We also implemented atomic operations, idempotency keys, and webhook signature verification to handle payment-related edge cases.
Audit Trail: Important actions, including milestone transitions, submissions, verification results, approvals, and payment events, are recorded.
Challenges we ran into
Building FairPay AI within 11 days came with several challenges.
Managing the milestone lifecycle: We had to implement a proper state machine to control how milestones move from creation to final payment. Each transition needed role-based permissions so that clients and freelancers could only perform the actions available to them.
Handling payment edge cases: PayPal integration was more complicated than we initially expected. We had to handle pending payments, declined captures, duplicate webhooks, failed database updates, and repeated requests without creating inconsistent payment records.
AI verification reliability: One of our biggest challenges was making sure AI didn't claim that something was completed without enough evidence. We introduced strict validation rules and kept unverified results separate from missing requirements.
Browser verification limitations: Not every requirement can be checked through screenshots or page observations. We had to account for situations where the available evidence was insufficient instead of forcing a pass-or-fail result.
Time management: With limited development time, we had to prioritise the main project-to-payment workflow rather than spending time on additional features such as a marketplace or built-in chat.
Accomplishments that we're proud of
There are a few things we're particularly happy with:
- We built a complete workflow that connects project creation, milestone agreements, work submissions, AI verification, client approval, and PayPal payments.
- We successfully integrated Gemini with Kernel to verify submitted project previews using actual browser observations.
- We introduced three verification outcomes instead of relying on a simple pass-or-fail score.
- We made sure AI remains advisory and that the final approval always belongs to the client.
- We implemented payment safeguards such as idempotency, atomic operations, and webhook verification.
- We added a demo mode so the complete workflow can be explored without depending on every external API configuration.
Most importantly, we managed to bring all these parts together into one working product within 11 days.
What we learned
This project taught us much more than just integrating different technologies.
We learned that AI should support human decisions rather than replace them, especially when money is involved.
We also realised that verification is not always straightforward. Sometimes evidence is incomplete, and it's better to honestly say that something cannot be verified than to provide a misleading result.
On the backend side, we gained practical experience with state machines, role-based access control, payment webhooks, idempotency, and handling failures in systems where multiple services communicate with each other.
We also learned the importance of keeping the scope realistic. Instead of trying to build everything, focusing on one complete and reliable workflow helped us deliver a more meaningful product.
What's next for FairPay-AI
We see several opportunities to make FairPay AI more useful in the future:
- More verification capabilities: Extend verification beyond visual inspection to include API testing, form submissions, functional checks, and other measurable requirements.
- More integrations: Support platforms such as GitHub, GitLab, and cloud hosting providers to verify code changes, deployments, and project progress.
- Additional payment options: Explore more payment providers and currencies to make the platform accessible to freelancers and clients across different countries.
- Better revision tracking: Allow freelancers to compare multiple submissions and see how each revision addresses previously identified issues.
- Improved verification reports: Provide more detailed evidence, clearer explanations, and better traceability for every criterion.
- Real-world testing: Work with actual freelancers and clients to understand their needs and improve the platform based on their feedback.
Our long-term vision is to make FairPay AI a reliable platform where clients and freelancers can work together with clearer expectations, transparent verification, and more confidence in payments.
Agree on the work. Verify it with evidence. Pay with confidence.
Built With
- express.js
- gemini
- github
- javascript
- mongodb
- mongoose
- node.js
- paypalapi
- react
- render
- typescript'