Inspiration
Global freelance and peer-to-peer digital work suffers from a massive $1.5T trust paradox. Clients hesitate to pay upfront before seeing working code, while freelancers hate shipping production code before knowing the funds are safely locked. Traditional freelance marketplaces solve this by acting as expensive middlemen—charging 5% to 20% in platform fees and relying on slow, manual human arbitration when disputes arise over whether a deliverable meets specifications.
Furthermore, once an agreement is reached, freelancers are often forced to act like debt collectors, sending awkward follow-up messages when clients forget to fund an invoice.
We wanted to eliminate both friction points by introducing true Agentic Commerce: putting an autonomous AI mediator, a friendly invoice nudge-bot, and a deterministic GitHub code auditor directly behind the wheel of PayPal’s Invoicing v2 and Payouts v1 APIs.
What it does
PayPact AI transforms plain-English chat negotiations into self-enforcing financial contracts across a 4-stage autonomous pipeline:
Autonomous Contract Negotiation (
NEGOTIATING):- The Client and Freelancer negotiate project scope, deliverables, and pricing in natural language inside the Negotiation Room.
- Powered by OpenAI (
gpt-4o-miniwith Strict Structured Outputs), the mediator extracts 5 mandatory contract parameters in real time (project_title,milestone_description,agreed_amount_usd,client_paypal_email, andfreelancer_paypal_email). - The system tracks readiness with a live parameter extraction card, keeping
agreement_reached: falseuntil both parties explicitly agree on all 5 fields.
Automated Escrow Invoicing & Friendly Nudge-Bot (
ESCROW_INVOICED):- The millisecond
agreement_reachedflips totrue, PayPact AI calls the PayPal Invoicing v2 API to generate a sequential invoice number, create a draft USD escrow invoice, and dispatch it to the Client (SENT/UNPAID). - 👋 Friendly Nudge-Bot: If an invoice sits unpaid, the freelancer can click the Nudge-Bot button. OpenAI drafts a warm, zero-pressure reminder ("Hey! Just a friendly heads-up that Invoice #PP-0092 is ready whenever you are...") and dispatches it via PayPal's native
/v2/invoicing/invoices/{id}/remindendpoint.
- The millisecond
Escrow Vault Lock (
ESCROW_FUNDED):- Once the Client pays the invoice (verified and recorded via PayPal's
/v2/invoicing/invoices/{id}/paymentsAPI), the invoice status transitions fromSENTtoPAID, locking the funds inside the PayPact Escrow Vault.
- Once the Client pays the invoice (verified and recorded via PayPal's
Deterministic AI Code Auditing & Instant Payouts (
PAYOUT_RELEASED):- The Freelancer submits a GitHub Pull Request URL, commit URL, or code snippet.
- Our backend fetches the raw
.diffor code content from GitHub and passes it to the OpenAI Code Auditor, which evaluates the implementation strictly against the lockedmilestone_description. - 🛡️ Escrow Guardrail: If the submitted code is incomplete or a
TODOplaceholder, the AI setsverified: false, logs a low confidence score, and blocks the payout (DELIVERABLE_CHANGES_REQUESTED) to protect the Client's funds. - 💸 Instant Release: When the code satisfies the milestone (
verified: true), PayPact AI immediately triggers the PayPal Payouts v1 API (POST /v1/payments/payouts), transferring the USD payout directly to the Freelancer's PayPal account.
AG Grid & AG Charts Studio Workspace:
- Every contract, invoice status, AI audit confidence score, and payout batch streams live into an interactive AG Grid & AG Charts command center equipped with custom cell renderers, KPI scoreboard tiles, and a Natural-Language Studio Agent that filters and sorts the ledger from plain-English prompts.
How we built it
- Backend & State Machine (
Node.js&Express): Built a modular REST API (server.js) managing the deal lifecycle acrossNEGOTIATING$\rightarrow$ESCROW_INVOICED$\rightarrow$ESCROW_FUNDED$\rightarrow$DELIVERABLE_CHANGES_REQUESTED$\rightarrow$PAYOUT_RELEASED. - PayPal Developer Platform (
paypal.js): Authenticated via OAuth 2.0 Client Credentials (POST /v1/oauth2/token) and integrated 6 distinct PayPal Sandbox REST endpoints:POST /v2/invoicing/generate-next-invoice-number(Sequential invoice numbering)POST /v2/invoicing/invoices(Draft escrow creation)POST /v2/invoicing/invoices/{invoice_id}/send(Autonomous invoice dispatch)POST /v2/invoicing/invoices/{invoice_id}/remind(Nudge-Bot reminders)GET /v2/invoicing/invoices/{invoice_id}&POST /v2/invoicing/invoices/{invoice_id}/payments(Escrow funding)POST /v1/payments/payouts(Idempotent batch payouts to freelancers)
- OpenAI Strict JSON Schema Agents (
agent.js): Usedresponse_format: { type: "json_schema", strict: true }across four specialized agents:processNegotiationTurn(Contract Mediator)verifyDeliverable(GitHub Code & Diff Auditor)generateFriendlyNudge(Zero-pressure Invoice Nudge-Bot)interpretGridCommand(Natural-Language AG Grid Studio Controller)
- Frontend & Sponsor Tools (
public/index.html,AG Grid,AG Charts,Render): Built a dark glassmorphic command center using Tailwind CSS, AG Grid Community (themeQuartzwith custom cell renderers for progress bars, status badges, and action buttons), AG Charts Community (live financial distribution donut chart), and deployed the full-stack service on Render (render.yaml).
Challenges we ran into
Cross-Timezone PayPal Invoice State Bugs (
SCHEDULEDvs.SENT):- While testing late at night in West Africa Time (
UTC+1), generating an invoice with a default UTC date (YYYY-MM-DD) caused PayPal's California servers (PST,UTC-8) to interpret the invoice date as "tomorrow." Instead of marking the invoice asSENT, PayPal placed it into aSCHEDULEDstate, which subsequently threw anUNPROCESSABLE_ENTITY(CANNOT_PROCESS_PAYMENTS) error when attempting to record an escrow payment. - How we fixed it: We engineered a timezone helper (
getPayPalServerDate()) usingIntl.DateTimeFormat('en-CA', { timeZone: 'America/Los_Angeles' })to synchronize all invoice and payment dates strictly with PayPal's server clock, paired with a resilient Sandbox vault fallback.
- While testing late at night in West Africa Time (
Preventing Premature Contract Locks & Hallucinated JSON:
- Early prompt iterations occasionally triggered invoice creation before both parties had provided their PayPal emails or agreed on the exact dollar amount.
- How we fixed it: We enforced OpenAI's
strict: trueJSON Schema validation with nullable fields and explicit system guardrails requiring all 5 contract fields to be non-null and mutually confirmed beforeagreement_reachedcan evaluate totrue.
Calibrating the AI Code Auditor:
- Initially, the code auditor was overly pedantic—rejecting valid Express.js code if a developer included helpful extras like a timestamp field in a JSON response. We tuned the auditor prompt and temperature (
0.1) so it strictly blocks broken or placeholder (TODO) code while passing implementations that fulfill the core contracted specification.
- Initially, the code auditor was overly pedantic—rejecting valid Express.js code if a developer included helpful extras like a timestamp field in a JSON response. We tuned the auditor prompt and temperature (
Accomplishments that we're proud of
- True End-to-End Autonomous Execution: Going from a plain-English chat conversation to a real PayPal Sandbox Invoice (
INV2-...), an AI-audited GitHub Pull Request, and a live PayPal Payout Batch (BATCH_...) without human back-office intervention. - The Escrow Guardrail in Action: Watching the AI Code Auditor inspect a bad commit, refuse to release the funds, explain the exact missing technical requirements, and then immediately release the PayPal Payout the moment valid code is submitted.
- Rich AG Grid Ledger & Studio Polish: Designing custom cell renderers, status pills, and interactive demo controls that turn a transaction table into an active FinTech command center.
- Judge-Friendly 1-Click Demo Buttons: Building instant demo prefill controls (
Demo: Client Offer,Demo: Freelancer Accept,Demo: Bad Code,Demo: Valid PR) that allow anyone testing our live Render deployment to experience every PayPal API and OpenAI agent in under 60 seconds.
What we learned
- Deep Mastery of PayPal’s Multi-Step Workflows: We learned how PayPal Invoicing v2 handles sequential numbering, draft creation, asynchronous dispatch, reminders, and external payment recording—and how cleanly it pairs with Payouts v1 for two-sided marketplace escrow.
- Grammar-Level Structured Outputs Are Essential for FinTech AI: When an LLM is given authority to trigger real financial APIs, conversational markdown is not enough. Combining deterministic state machines with OpenAI's
json_schema(strict: true) gives AI agents reliable, production-grade guardrails. - Dashboard UX as an Active Workspace: Building with AG Grid and AG Charts showed us how a financial ledger can evolve from a passive log into an interactive control plane.
What's next for PayPact AI
- Multi-Milestone Split Contracts: Supporting staged payouts where a single PayPal Escrow Invoice funds multiple sequential milestones, releasing partial payouts as each Pull Request is merged.
- Live GitHub App & CI/CD Webhook Triggers: Automatically triggering
/verify-and-payoutthe second a GitHub Pull Request passes automated unit tests and is merged intomain. - PayPal Webhooks Integration: Listening to live
INVOICING.INVOICE.PAIDandPAYMENT.PAYOUTS-ITEM.SUCCEEDEDwebhook events to transition deal states asynchronously in production. - Multi-Modal Deliverable Auditing: Expanding the OpenAI Auditor beyond code diffs to verify design deliverables (Figma exports, UI screenshots) and live deployed URLs.
Built With
- ag-charts
- ag-grid
- axios
- css3
- express.js
- gpt-4o-mini
- html5
- javascript
- node.js
- oauth2
- openai
- paypal
- paypal-invoicing-api
- paypal-payouts-api
- paypal-sandbox
- render
- rest-api
- tailwindcss