PayFlow Copilot

AI quote-to-payment agent that converts client chat into structured invoices, automates PayPal checkout, and delivers grounded financial analytics.

Comment

💡 Inspiration

Freelancers, independent consultants, and small business creators spend up to 25% of their working hours trapped in administrative friction: copying unstructured scopes from WhatsApp or email threads, manually compiling invoices, chasing overdue client accounts, and struggling with complex payment integrations.

We asked ourselves: What if an AI agent could seamlessly bridge the gap from informal client conversations to real, verified money in the bank?

That vision inspired PayFlow Copilot — an autonomous quote-to-payment agent that extracts itemized billable work from natural-language messages, validates financial totals using rigorous Decimal mathematics, executes secure checkouts via PayPal Sandbox, and provides audit-grade transaction tracking with zero financial hallucination.

⚙️ How We Built It

We engineered PayFlow Copilot as a high-assurance financial platform with strict separation of concerns:

1. Conversational Extraction with Gemini 2.5 Flash

Using the official Google Gen AI Python SDK (google-genai), the agent analyzes unstructured customer briefs (e.g., "Create a quote for Alex: 2 banners at $35 each and one logo revision at $20"). Through structured JSON outputs and Pydantic schemas, it identifies:

  • Customer identity and contact information
  • Deliverable descriptions
  • Integer quantities ( q_i )
  • Unit prices ( p_i )

2. Zero-Hallucination Server-Side Math

To guarantee mathematical precision and prevent AI rounding or pricing errors, monetary totals are computed strictly in Python backend code using Decimal arithmetic:

$$ \text{Subtotal} = \sum_{i=1}^{n} (q_i \times p_i) $$ $$ \text{Total Billed} = \text{Subtotal} + \text{Tax} - \text{Discount} $$

The AI is explicitly prohibited from inventing or hallucinating unit prices. If pricing or customer information is absent, the agent gates the quote as is_ready_for_approval: false and flags missing fields.

3. PayPal Sandbox Orders API v2 & JavaScript SDK v6

Once the business owner reviews and approves the quote, PayFlow Copilot provisions a server-side order via PayPal's Orders API v2 (intent: CAPTURE). The client completes checkout in sandbox mode. The backend enforces two critical safety rules:

  • Server-Side Verification: A transaction is never marked as paid based merely on client-side browser events. The server executes a verified capture against PayPal's REST endpoints and validates the COMPLETED capture status and paypal_capture_id.
  • Idempotency Protection: Using request keys and database unique constraints, repeated requests return existing verified records without duplicate captures.

4. High-Performance Audit Ledger & Grounded Analytics

  • AG Grid Community v33: Provides an interactive financial audit log with multi-column sorting, real-time filtering, pagination, drawer audit view, and 1-click CSV export.
  • Grounded AI Business Insights: The agent answers questions like "What is my average order value?" or "Which customers need follow-up?" by computing actual PostgreSQL/SQLite aggregates first and feeding only verified metrics to Gemini.

🧗 Challenges We Faced

  1. Eliminating LLM Price Hallucinations: Language models naturally attempt to calculate math or guess missing prices. We solved this by enforcing strict Pydantic schemas, stripping pricing math away from the model prompt, and running validation through Python's Decimal('0.01', rounding=ROUND_HALF_UP).
  2. Preventing Race Conditions & Duplicate Captures: Network retries in payment systems can trigger accidental double-charges. We implemented idempotency key checks and database uniqueness constraints on both paypal_order_id and webhook event IDs.
  3. Zero-Secret Frontend Architecture: To ensure enterprise-grade security, the PayPal client secret and Gemini API key are kept strictly on the backend, ensuring only public sandbox client IDs reach the browser bundle.

🎓 What We Learned

  • How to implement the latest Google Gen AI Python SDK with type-safe structured JSON schemas.
  • Deep hands-on integration with PayPal Orders API v2, server captures, and cryptographic webhook signature verification.
  • Designing human-in-the-loop financial UX that balances agentic automation with human control.
  • Architecting high-performance data grids using AG Grid Community inside a modern React 18 / Vite / Tailwind stack.

🔮 What's Next for PayFlow Copilot

  • Automated Multi-Channel Invoicing: Direct WhatsApp and Slack bot integrations to trigger quotes from team communication channels.
  • Multi-Currency FX Support: Dynamic currency conversion and multi-currency PayPal checkout accounts.
  • Recurring Subscriptions & Retainers: Automated monthly retainer invoicing for ongoing freelance contracts.
  • Supabase Edge Functions: Webhook processing at the edge for sub-millisecond payment notification updates.

Built With

Share this project:

Updates

Submission history