Inspiration

Freelancers, independent consultants, and small agencies spend far too much time switching between client notes, invoice forms, payment links, and spreadsheets just to get paid. Even worse, chasing overdue invoices and writing follow-up reminders manually takes focus away from actual client work.

We asked ourselves: What if creating and tracking a payment request was as simple as typing one natural sentence—while still keeping a human in full control before any link is generated or money is moved? That idea inspired PayPilot AI.

What it does

PayPilot AI is an AI-powered fintech web application that takes users from a plain-English conversation to a verified PayPal Sandbox payment:

  • AI Payment Agent (/ai-agent): Type a message like "Request $250 from John for website development due next week". PayPilot AI parses the client, service, amount, currency, and due date, matches existing clients in your CRM, and asks clarifying questions if details are missing.
  • Human-in-the-Loop Approval: The AI never sends invoices automatically. It builds a structured Payment Proposal Card for the user to review and approve with one click before generating a shareable checkout link (/pay/:token).
  • Hosted PayPal Sandbox Checkout (/pay/:token): Clients do not need an account to pay. They open the checkout link, review the itemized breakdown, and pay via PayPal, Pay Later, Debit or Credit Card (PayPal JS SDK), or PayPal Sandbox Redirect.
  • Dedicated Payment Result States: Includes real-time Processing, Payment Successful! (with verified PayPal Capture ID, Order ID, amount, currency, date/time, and status), Payment Cancelled, and Payment Failed states with retry support.
  • Real-Time Dashboard, CRM & Reporting: Automatically updates total revenue, pending volume, client payment history, notifications, Verified Transactions (/transactions), AI Business Insights (/insights), and CSV Revenue Exports (/reports).

How we built it

We architected PayPilot AI as an integrated full-stack TypeScript application:

  • Frontend: Built with React 19, TypeScript, Vite, Tailwind CSS 4, React Router v7, Motion, and Lucide React for a responsive blue-and-white fintech UI across desktop, tablet, and mobile.
  • Backend & Security: Built on Node.js and Express 4 with scryptSync password hashing, HMAC-SHA256 signed HttpOnly session cookies, per-user data isolation (ownerId), and sliding-window rate limiting on auth and AI routes.
  • AI Integration: Powered by Google Gemini (@google/genai) on the server side to parse payment instructions, generate service descriptions, draft overdue payment reminders, and summarize financial insights—with a deterministic fallback when no API key is present.
  • PayPal Sandbox Integration: Uses PayPal Orders API v2 (intent: CAPTURE) and the PayPal JavaScript SDK. All order creation, OAuth token caching, return_url / cancel_url generation (via a central environment-independent APP_URL), capture verification, amount/currency validation, and idempotency checks happen strictly on the backend.
  • Persistence: Uses a zero-setup, file-backed JSON store (data/store.json) with clean repository methods so revenue and transaction states persist across server restarts.

Challenges we ran into

  • Environment-Independent PayPal Redirects: Ensuring PayPal return and cancellation URLs work seamlessly in both local development (http://localhost:3000) and live Render deployment (https://paypilot-ai-zz8c.onrender.com) without hardcoding URLs or changing code between environments.
  • Strict Capture Verification & Idempotency: Preventing duplicate PayPal orders, rejecting mismatched amounts or order IDs, and ensuring repeated capture calls return the existing verified transaction instead of double-counting revenue.
  • Keeping Checkout Honest: Designing clear Processing, Cancelled, and Failed states so a payment is never marked COMPLETED in the UI or database until the backend verifies COMPLETED status directly from PayPal's capture response.
  • Seamless Dashboard Synchronization: Making sure completed Sandbox payments immediately update client balances, dashboard metrics, and the Transactions ledger without requiring manual refreshes.

Accomplishments that we're proud of

  • Built a complete end-to-end Conversation → Proposal → Approval → PayPal Sandbox Checkout → Verified Capture → Dashboard Sync workflow.
  • Implemented strict Human-in-the-Loop AI safety alongside server-side payment verification so neither AI output nor client-side requests can ever forge a completed payment.
  • Designed a clean, responsive fintech interface with 16+ routes covering public marketing, authentication, onboarding, AI chat, CRM, invoicing, hosted checkout, analytics, and CSV reporting.
  • Verified core auth, user isolation, APP_URL normalization, PayPal order/capture validation, and idempotency with automated integration tests (npm test), TypeScript checks (npm run lint), and production builds (npm run build).

What we learned

  • Never trust client-side payment status: Payment state transitions must always be verified server-to-server against the payment gateway's capture response (status, reference_id, currency_code, and value).
  • Centralized configuration saves deployment headaches: Normalizing APP_URL in one backend config module with startup validation prevents broken redirects between localhost and cloud hosting.
  • AI works best with guardrails: Combining LLM flexibility with structured JSON schemas and explicit user approval gives users speed without sacrificing accuracy.

What's next for PayPilot AI

  • PayPal Webhooks: Adding asynchronous webhook verification (PAYMENT.CAPTURE.COMPLETED) for extra resilience if a user closes their browser before redirect completes.
  • Database Migration: Upgrading the file-backed JSON store to PostgreSQL for multi-instance cloud scaling.
  • Multi-Currency & Recurring Billing: Supporting automated recurring retainers, tax calculations, and scheduled reminder emails.

Built With

Share this project:

Updates

Submission history