💡 Inspiration

Finance teams waste hundreds of hours manually reviewing vendor invoices, chasing approvals for routine SaaS subscriptions, and missing early-payment discounts—while rogue charges and billing drift slip through undetected.

We asked: what if a trusted AI agent could sit inside accounts payable as a financial firewall? One that extracts invoice data from raw PDFs, audits every line item against deterministic policy rules, and executes verified sandbox payouts via PayPal Payouts API—while keeping a human in the loop for every high-value or ambiguous decision.

That is AgentPay.


⚙️ What It Does

AgentPay is a multi-vendor invoice processing sandbox that demonstrates safe, bounded LLM tool-calling for financial workflows.

The core pipeline:

  1. Upload — Users upload a selectable-text PDF containing multiple vendor invoices (up to 200 pages / 4 MB).
  2. Extract — The server extracts text from the PDF (unpdf) and sends character-budget chunks to an LLM via OpenRouter to produce structured invoice objects.
  3. Audit — Each invoice is run through a pure-deterministic rule engine (hard caps, monthly velocity budget, pre-registered recipient check, arithmetic validation) and an optional LLM free-text custom rule check.
  4. Decide — Invoices that pass guardrails are approved for payout; borderline ones go to human review; hard-rule violations are rejected. Every decision shows the exact rule ID and reason.
  5. Pay — Approved invoices trigger PayPal Payouts REST API sandbox disbursements to pre-registered recipient email addresses.
  6. Reconcile — Payout item status is polled and surfaced in a live Payouts tab (PENDING → SUCCESS / UNCLAIMED / FAILED).

Key safety principle — the LLM proposes, deterministic code disposes:

The model can only supply an invoice ID and a reasoning string. It cannot alter the payment destination, amount, or currency. All monetary decisions are made by the deterministic engine operating on user-configured guardrails stored in the database.


🛠️ How We Built It

Layer Technology
Framework Next.js 16 (App Router), React 19, TypeScript strict mode
Styling Tailwind CSS, Geist / Geist Mono fonts, tabular numerals
Auth & DB Supabase Auth (Google OAuth), PostgreSQL with Row-Level Security
PDF Parsing unpdf — server-side text extraction with character-budget chunking
AI / LLM OpenRouter (model-agnostic) with structured JSON schema output
Payments PayPal Payouts v1 REST API — sandbox only, AES-256-GCM encrypted credential vault
Testing Vitest + PGlite (embedded Postgres) — 101 unit/integration tests; Playwright browser automation

Architecture

The domain engine (src/lib/engine) is a pure TypeScript module with zero external dependencies — it validates, caps, and audits invoices entirely in memory. Provider adapters (LLM, PayPal, Supabase) are injected at service boundaries, making every business rule fully testable offline.

Financial precision: all monetary values are stored and computed in integer cents to eliminate floating-point drift.

Resumable batch processing: a 5-minute per-user database lease serializes concurrent requests, prevents duplicate payouts across retries, and survives page refreshes.


🚧 Challenges We Ran Into

  • Keeping AI influence strictly bounded: designing the agent interface so the model can never influence the recipient address or amount required explicit port contracts and careful test coverage of the injection surface.
  • Floating-point arithmetic: multi-line invoice taxes and partial approvals exposed edge cases. Solved by converting all values to integer minor units (Math.round(dollars * 100)) at every system boundary.
  • Resumable batch orchestration: multi-invoice PDFs can stall mid-batch on API quota. Implementing idempotent chunk cursors, database leases, and retry semantics that reuse original batch IDs took multiple design iterations.
  • PayPal Payouts item-level reconciliation: a batch-level SUCCESS does not guarantee every item succeeded. The reconciler must poll individual item status and treat UNCLAIMED as an in-progress state requiring human follow-up.
  • Sandbox-only enforcement: hard assertions in the PayPal client reject any non-sandbox host at the HTTP layer, not just configuration, so live credential leakage is impossible.

🏆 Accomplishments We're Proud Of

  • 101 automated tests covering domain rules, money arithmetic, batch orchestration, embedded PostgreSQL RLS isolation, encrypted wallet credentials, and browser UI interactions — all passing offline without external credentials.
  • A clean, evidence-led dashboard design inspired by Mercury and Linear — zero decorative AI-slop, every status badge backed by an explicit rule ID.
  • A full end-to-end sandbox payout trail: PDF upload → LLM extraction → deterministic audit → PayPal Payouts API → reconciled status — all verifiable in the browser.

📚 What We Learned

  • PayPal's Payouts batch API is flexible but requires careful item-level reconciliation: batch success ≠ item success.
  • Deterministic guardrails alongside an LLM create a more trustworthy system than either alone — the model handles unstructured perception, the rule engine handles monetary authority.
  • Embedded PGlite (in-process PostgreSQL) is a game-changer for testing RLS policies and schema migrations without a live database server.

🔮 What's Next for AgentPay

  • MCP (Model Context Protocol) server endpoint: let Claude, GPT, or any MCP-compatible agent call agentpay_process_invoice directly from a chat or terminal session.
  • OCR support for scanned PDF invoices via a vision model on OpenRouter.
  • Multi-tenant organization support with role-based approval governance (Finance Controller, AP Clerk, Viewer).
  • Webhook ingestion for real-time PayPal PAYMENT.CAPTURE.COMPLETED events.
  • Expanded currency support beyond USD.

Built With

  • agent
  • next
  • openrouter
  • paypal
  • supabase
Share this project:

Updates

Submission history