💡 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:
- Upload — Users upload a selectable-text PDF containing multiple vendor invoices (up to 200 pages / 4 MB).
- Extract — The server extracts text from the PDF (
unpdf) and sends character-budget chunks to an LLM via OpenRouter to produce structured invoice objects. - 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.
- 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.
- Pay — Approved invoices trigger PayPal Payouts REST API sandbox disbursements to pre-registered recipient email addresses.
- 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
SUCCESSdoes not guarantee every item succeeded. The reconciler must poll individual item status and treatUNCLAIMEDas 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_invoicedirectly 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.COMPLETEDevents. - Expanded currency support beyond USD.
Built With
- agent
- next
- openrouter
- paypal
- supabase