Inspiration
Every small business owner knows this moment. You send an invoice, the due date passes, and nothing happens. Then the replies trickle in, one at a time:
- "We need a PO number on this before we can pay."
- "I already paid that last week."
- "Can we pay half now and half next month?"
- "Any chance of a discount?"
None of these is a big problem. But each one needs someone to read it, work out what's actually wrong, check the payment records, and write back. For a small team, that is hours every week spent on work that doesn't grow the business. Meanwhile the money sits in someone else's account and cash flow stalls. Late payments are one of the most common reasons small businesses get into trouble, even profitable ones.
The work is repetitive and rule-driven, which suits an AI agent. But it also involves real money and real customers. An agent that reminds someone who already paid, or quietly gives away a discount, is worse than no agent at all. That tension is what we wanted to explore: how much can you hand to an AI agent when the stakes are real?
PayPal's Invoicing API gave us a good place to try it. It has what the workflow needs: invoices, reminders, partial payments, a payer-facing page, and webhooks that confirm when money actually lands. Our idea was simple: let the AI do the thinking and chasing, and keep every decision about money behind hard rules it cannot override.
What it does
CashFlow AI watches a business's PayPal invoices and handles the ones where money is stuck. It works in three steps:
- Detect: Java rules flag the problem: overdue, paid but not matched in the books, partially paid, or a promised payment that never arrived.
- Understand and act: an LLM agent works out why (missing PO, silent customer, discount request, and so on) and takes one action through a fixed set of tools.
- Check: every action goes through a policy engine first.
- Runs automatically: reading data, checking payments, recording a diagnosis, escalating to a human.
- Needs the owner's approval: sending reminders, reconciling payments, updating a PO, payment plans.
- Never allowed: discounts, refunds, write-offs, changing an amount. In our demo a customer asks for 20% off, the agent tries, the policy blocks it, and the case goes to a human.
Around that loop we built five more features:
- Paid check: before any reminder goes out, the agent must look for the payment in PayPal. It matches on exact reference, then typos, then same payer and amount. In our demo a customer paid with the reference "INV-1O9" (a letter O instead of a zero), and the agent still found it and did not chase.
- Fix & Pay page: every reminder links to a page where the customer can add a PO, report a payment, agree to a payment plan, promise a date, or dispute. Plans stay inside the owner's limits (at most 2 installments over 30 days, 50% or more up front) and are enforced with PayPal partial payments.
- MCP: the customer's own AI agent can do the same things through 10 MCP tools, with the same policy engine and audit log. It only sees that customer's invoices.
- Webhooks: signature-verified PayPal events reconcile payments and close cases. A PayPal dispute event stops all chasing on that invoice.
- Earned autonomy: after the owner approves the same type of action 3 times in a row, the app offers to let the agent do it alone. This only applies to reminders, PO updates, and reconciliation. One rejection takes it back.
How we built it
- Backend: Java 21, Spring Boot, and PostgreSQL. Detection, policy, and the case lifecycle are plain deterministic Java. All money math uses
BigDecimal, so the model never calculates an amount. - Agent: a tool-calling loop running
gpt-oss-120bon Groq (Anthropic also works), capped at 8 steps per case. A scripted stand-in lets the whole demo run with no API key. - PayPal: the Invoicing v2 API for OAuth, creating and sending invoices, reminders, reading an invoice, and updating it to add a PO or partial-payment settings. We verify webhook signatures through PayPal's verification endpoint. All of it was built and tested against the PayPal sandbox.
- Frontend: React, Vite, and TypeScript, with AG Grid for the invoice table, AG Charts for aging and case analytics, and Bryntum Calendar for the timeline of promised dates and follow-ups.
- Audit trail: every tool call, policy decision, customer action, and webhook is saved with who did it.
- Deployment: Render, using Docker and managed Postgres.
Challenges we ran into
- Keeping the model away from money: the model only chooses which tool to call. Policy, arithmetic, and duplicate-action protection live in Java, so a bad model output can't move money.
- PayPal's update is a full replace: to add a PO or turn on partial payments, we have to read the invoice, change one field, and PUT the whole thing back. Getting that right without sending fields PayPal rejects took trial and error. [Add one real detail: which error you hit and how you fixed it.]
- The paid check: not chasing someone who already paid sounds simple. In practice it needed three levels of matching (exact reference, typo, same payer and amount) and went through the most iterations.
- Designing for the other side's agent: we had to decide what a customer's agent may do over MCP, so it can negotiate within the owner's limits without seeing anyone else's data.
What we learned
- PayPal's Invoicing v2 API is richer than it looks:
partial_paymentconfig,recipient_view_url, and webhook verification map cleanly onto a real accounts receivable workflow. - Guardrails beat prompts: the most reliable AI safety we found is a Java policy engine the model can't bypass.
- The other side's agent matters: in B2B payments, a smarter reminder often isn't the fix. Giving the customer's own agent a structured way to clear the block is.
What's next for CashFlow AI
- Live sandbox and production rollout: run the full flow on real PayPal sandbox invoices and webhook events, tune the agent against what actually comes back, then move to a production PayPal account.
- Learning from outcomes: use the audit trail we already keep to see which reminders, payment plans, and wording actually get invoices paid, and use that to pick better actions and timing for each customer.
- Agent-to-agent negotiation: extend the MCP interface so a merchant's agent and a customer's agent can work through longer back-and-forth, such as counter-offers on payment plans, always inside the owner's limits.
- More invoicing systems: the detection, policy engine, and agent tools are not tied to PayPal. Adding connectors for other invoicing and accounting tools would let more small businesses use the same guardrails.
Built With
- ag-charts
- ag-grid
- bryntum-calendar
- docker
- groq
- java
- llm-agent
- model-context-protocol-(mcp)
- paypal-developer-platform
- paypal-invoicing-api
- paypal-webhooks
- postgresql
- react
- render
- rest-api
- spring-boot
- tool-calling
- typescript
- vite