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:

  1. 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-mini with Strict Structured Outputs), the mediator extracts 5 mandatory contract parameters in real time (project_title, milestone_description, agreed_amount_usd, client_paypal_email, and freelancer_paypal_email).
    • The system tracks readiness with a live parameter extraction card, keeping agreement_reached: false until both parties explicitly agree on all 5 fields.
  2. Automated Escrow Invoicing & Friendly Nudge-Bot (ESCROW_INVOICED):

    • The millisecond agreement_reached flips to true, 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}/remind endpoint.
  3. Escrow Vault Lock (ESCROW_FUNDED):

    • Once the Client pays the invoice (verified and recorded via PayPal's /v2/invoicing/invoices/{id}/payments API), the invoice status transitions from SENT to PAID, locking the funds inside the PayPact Escrow Vault.
  4. 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 .diff or code content from GitHub and passes it to the OpenAI Code Auditor, which evaluates the implementation strictly against the locked milestone_description.
    • 🛡️ Escrow Guardrail: If the submitted code is incomplete or a TODO placeholder, the AI sets verified: 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.
  5. 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 across NEGOTIATING $\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): Used response_format: { type: "json_schema", strict: true } across four specialized agents:
    1. processNegotiationTurn (Contract Mediator)
    2. verifyDeliverable (GitHub Code & Diff Auditor)
    3. generateFriendlyNudge (Zero-pressure Invoice Nudge-Bot)
    4. 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 (themeQuartz with 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

  1. Cross-Timezone PayPal Invoice State Bugs (SCHEDULED vs. 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 as SENT, PayPal placed it into a SCHEDULED state, which subsequently threw an UNPROCESSABLE_ENTITY (CANNOT_PROCESS_PAYMENTS) error when attempting to record an escrow payment.
    • How we fixed it: We engineered a timezone helper (getPayPalServerDate()) using Intl.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.
  2. 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: true JSON Schema validation with nullable fields and explicit system guardrails requiring all 5 contract fields to be non-null and mutually confirmed before agreement_reached can evaluate to true.
  3. 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.

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-payout the second a GitHub Pull Request passes automated unit tests and is merged into main.
  • PayPal Webhooks Integration: Listening to live INVOICING.INVOICE.PAID and PAYMENT.PAYOUTS-ITEM.SUCCEEDED webhook 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

Share this project:

Updates

Submission history