Inspiration
Small transport businesses pay dozens of small bills every week — fuel, repairs, parts, relief drivers. The bills arrive as phone photos, the owner types them in by hand, and nobody notices when the same invoice is paid twice, a mechanic suddenly charges three times the usual price, or a brand-new "vendor" asks to be paid. We wanted an AI that does the boring reading and checking, and a payment rail that pays everyone at once — without ever letting the AI move money on its own.
What it does
- Reads bills with AI. Upload photos or PDFs; Gemini extracts vendor, amount (exactly as printed), currency, date, invoice number, payee PayPal email and category, with a confidence score per field.
- Checks every bill and explains each flag in plain English: duplicate invoice, overcharge (more than 2× the vendor's average), first-time payee, and the per-bill spending limit.
- Asks a human when unsure. Low-confidence bills open a review screen with the original photo next to the form and the unsure fields highlighted.
- Pays with PayPal Payouts. In an AG Grid approval table the owner selects bills, sees every payee and the total, types a reason for any flagged bill, and pays everyone in one PayPal Payouts batch. Bills become "Paid" only when PayPal reports SUCCESS.
- Payment Assistant (agentic commerce). "Pay all clean fuel bills from this week" → the agent builds a payment plan, explains why each bill is in or out, and hands it to the same human approval step.
How we built it
- PayPal: OAuth2 client credentials with token caching; Payouts API create (
POST /v1/payments/payouts) with one item per approved bill; status sync (GET /v1/payments/payouts/{id}) mapping SUCCESS / PENDING / UNCLAIMED / FAILED / RETURNED and more; idempotency withsender_batch_idandPayPal-Request-Id, so a retried request can never pay twice. - AI: Google Gemini (
gemini-3.5-flash-lite) in JSON mode with a response schema, validated again with zod — for bill extraction (vision) and for turning the owner's instruction into selection criteria only. A deterministic plan engine applies the criteria, guardrails and a $5,000 cap; bill ids the AI might return are stripped. - App: Next.js 16, React 19, TypeScript, Tailwind, AG Grid Community, Supabase Postgres + Storage with row-level security, deployed on Vercel.
- Safety in the database: every status change and its audit row are one transaction; a partial unique index allows only one live payout per bill; a trigger lets payout outcomes only move forward; approving a flagged bill without a reason is rejected by the database itself.
- Testing: 205 automated tests including 13 property-based properties (fast-check) for money conversion, the checks, PayPal request building, status mapping and plan safety — plus opt-in live tests against Gemini, Supabase and the PayPal sandbox.
Challenges we ran into
- PayPal country rules: our first sandbox business account was in a country that cannot send Payouts (
PAYOUT_NOT_AVAILABLE). The app handled it correctly (batch rejected, bills "Payment failed", retry allowed); a US sandbox business account fixed it. - Unknown outcomes: if PayPal times out, did the money move? We never guess — the batch stays "submitting" and is resent with the same request id, which PayPal treats as the same payout.
- Batch status lag: PayPal's batch can still say PROCESSING after every item succeeded, so the UI derives "Completed" from the items.
- Model availability: the newest Gemini Flash models returned 503 "high demand" during testing; we benchmarked and picked one that reads every sample bill correctly in 1.5–3.5 s.
Accomplishments that we're proud of
- Real end-to-end payouts in the PayPal sandbox — including a flagged bill approved with a written reason and a plan suggested by the AI agent — with transaction ids shown in the app.
- An agent that is useful but provably bounded: it can't pick bills, can't exceed limits, can't include flagged bills unless asked, and can't pay.
- "Never pay twice" enforced in three independent layers.
What we learned
Agentic payments are safest when the AI's job is narrowed to understanding intent, while selection, limits and money movement stay in deterministic, testable code — with a human approval in front of PayPal.
What's next for FleetSpend AI
- PayPal webhooks instead of polling, and multi-user approval roles (two approvals above a threshold).
- More currencies and an India version using local payout rails.
- Learning normal prices per vendor and route to catch subtler overcharges.
Try it
Live demo (PayPal sandbox): https://fleetspend-ai.vercel.app — click Reset demo, then Try the 8 sample bills.
Built With
- ag-grid
- fast-check
- google-gemini
- nextjs
- paypal
- paypal-payouts
- postgresql
- react
- supabase
- tailwindcss
- typescript
- vitest
- zod
