How it works, in plain words
A freelancer creates an invoice in LedgerGuard, which creates and sends a real PayPal invoice through the PayPal Invoicing API. The client pays on PayPal's own page, not inside LedgerGuard. PayPal can notify LedgerGuard by webhook, or the freelancer can click Sync with PayPal; either way the invoice turns Paid and any pending reminder drafts are cancelled. If the client is late, Claude reads the invoice context and drafts a reminder, which the freelancer reviews, approves, and then sends themselves. If the client opens a dispute, LedgerGuard gathers evidence from the invoice trail and drafts a defense that cites its sources. That defense goes to PayPal only after the freelancer approves and confirms. The freelancer can also ask questions in plain English; the model turns the question into a filter, and code computes the exact numbers.
Judge access
- Landing: https://ledgerguard-web.onrender.com · Demo app: https://ledgerguard-web.onrender.com/app · API: https://ledgerguard-api-i7i3.onrender.com (OpenAPI docs at
/docs). - No login needed.
/loginis a demo screen; "Continue to demo" opens the app. - Both services run on Render's free plan and sleep when idle. The first request can take about a minute while they wake; reload if the app shows "API offline".
- The hosted demo runs in PayPal Sandbox mode. Judges will see PayPal Sandbox in the sidebar, not Demo (mock).
- The demo uses SQLite on an ephemeral disk and re-seeds its demo data on every boot, so changes you make are reset after a restart.
- Verified live: On 11 Nov 2026 the hosted app ran in PayPal Sandbox mode. A sandbox personal buyer paid two invoices on PayPal's own page, and LedgerGuard marked both Paid after Sync with PayPal: LG-2026-1016-04EB (PayPal INV2-GRCS-7EKA-KPLM-47R3, GBP 25,000) and LG-2026-1017-56AD (PayPal INV2-ZTWF-CPQH-YLWP-JAEC, EUR 18,000). Screenshots of the second payment are in the README under Proof: a real PayPal sandbox payment.
- Step-by-step test instructions, including a quick test with no PayPal account and a full sandbox payment test, are in the README under How to test it (judges).
Why LedgerGuard (positioning)
Other tools either chase invoices or fight disputes. LedgerGuard is the only one that uses your invoice trail to win the dispute, built natively on PayPal.
- All three jobs in one PayPal-native app: invoice chasing, dispute defense and a conversational ledger share one invoice ledger, so nothing is copied between tools.
- Dispute evidence built from the invoice and reminder history, not just order data. The defense draws on the signed scope, milestones, deliveries, every reminder sent and the client's replies, and each claim cites its source.
- Guardrails enforced in code, made for cross-border freelancers. Late-fee caps, exact per-currency totals and human approval before anything reaches PayPal are rules in code, not prompts. It is built for freelancers in markets like Kenya who are paid from abroad.
Inspiration
I am a freelance developer in Nairobi, and most of the people who pay me are in the US and Europe. For a freelancer or a two-person agency in Kenya, money tied up in an unpaid invoice is often money you need this month. Three problems keep coming back:
- Late payments. You send the invoice, the due date passes, and you have to decide how hard to push. If you are too soft you do not get paid. If you are too harsh you can lose a good client. Writing the right email for a formal German finance team is different from writing one for a friendly UK design studio.
- Chargebacks and disputes. A buyer says the work "was not as described", and you have a deadline to reply. The proof (signed scope, milestone approvals, delivery notes, the client's "looks great!") is spread across email, chat and repos. While the dispute is open, that money is frozen.
- No clear picture. "Which invoices over $1,000 are past due?" should take seconds to answer. A small business usually has no analyst to ask, and a chatbot that guesses the numbers is worse than no answer.
PayPal already offers the right primitives: Invoicing, Webhooks and Disputes. LedgerGuard AI puts an agentic layer over them, sized for one freelancer, with a hard rule that the AI drafts and the human decides.
Side story: While building the PayPal client, webhook handling and mock layer, I noticed that most of that plumbing (OAuth, retries, idempotency, signature checks, a mock that behaves like the sandbox) is what every developer here has to rebuild. It could be packaged as an easy PayPal connector for African developers. That is an idea for later, not part of this submission. See What is next.
What it does
LedgerGuard AI is a web app with three workflows. All three run against the PayPal sandbox when credentials are configured. Without credentials, a mock client that returns the same response shapes is used instead, so anyone can run the demo.
1. Invoice chaser: state machine plus tone-aware AI reminder drafts
- Create and send invoices with the PayPal Invoicing API v2 (
POST /v2/invoicing/invoices, thenPOST /v2/invoicing/invoices/{id}/send). - Each invoice moves through an explicit state machine:
draft → sent → due_soon → due → overdue_3 → overdue_7 → paid(pluscancelled). Invalid transitions are rejected. Paying is idempotent, and paid or cancelled invoices are terminal. - A LangGraph reminder agent runs five nodes:
gather_context → analyze_sentiment → decide_next_action → apply_guardrails → draft_message.- Context: amount, due date, days overdue, the client's country, how late they paid past invoices, and their recent messages.
- Sentiment: the LLM scores the client's recent messages. A lexicon scorer is the fallback.
- Decide: Claude chooses the next action (wait, remind, offer a split, offer Pay Later, escalate), the tone (friendly, neutral or firm) and a suggested late-fee percentage, with a rationale. Without a model, deterministic rules make the same decision.
- Guardrails (code): the fee is capped at 1.5% and allowed only from 7+ days overdue, and dropped when a split or Pay Later is offered; escalation needs 14+ days overdue; before the due date there is no firm tone and only a plain reminder; split installments are computed exactly and sum to the total. The fee amount is computed in code, never by the model.
- Draft: the LLM writes the email with country guidance (US: direct, net terms; DE: formal, cites the contract clause; GB: polite and understated; NL: direct; KE: warm). It is told to use only the amounts, dates, fee and installments it is given. A draft that mentions a fee the policy removed is replaced with a template, and a template is also used when no model is configured.
- The UI shows the agent's reasoning beside each draft: risk, sentiment score, days overdue, and how late the client usually pays.
- Nothing is ever sent automatically. "Approve" only marks a draft as approved. You copy the text and send it yourself.
- Payment detection: an
INVOICING.INVOICE.PAIDorPAYMENT.CAPTURE.COMPLETEDwebhook marks the invoice paid and cancels its pending reminder drafts. Without a public webhook URL, Sync with PayPal pollsGET /v2/invoicing/invoices/{id}for every open invoice and uses the same mark-paid path.
2. Dispute defense: evidence search plus an AI defense package, approved by a human
- A
CUSTOMER.DISPUTE.CREATEDwebhook (or Sync, which callsGET /v1/customer/disputes) starts the flow. The backend fetches the full dispute withGET /v1/customer/disputes/{id}and matches it to the invoice and client. - A LangGraph dispute agent runs
search_evidence → build_timeline → draft_narrative:- Search: full-text search (SQLite FTS5 with BM25, or Postgres
tsvector) over that client's stored contracts, milestones, delivery notes, messages and files. Each dispute reason has its own query terms, and the buyer's own message is added to the query. Evidence linked to the disputed invoice is always included. - Timeline: the evidence in date order, each item with its evidence ID.
- Statement: a calm, factual response of under 250 words that cites evidence IDs in brackets. The prompt tells the model to use only the evidence provided. A deterministic composer writes the statement when no model is configured.
- Search: full-text search (SQLite FTS5 with BM25, or Postgres
- The package also lists the milestones it references and a ready-to-send
provide-evidencepayload (PROOF_OF_FULFILLMENTfor "not received", otherwiseOTHER). - Nothing is submitted until you click "Approve & submit evidence" and then confirm. Only that step calls
POST /v1/customer/disputes/{id}/provide-evidence. The server refuses a second submission of the same package. - The page also shows an evidence library (exact counts of stored evidence per client and type) and a feed of recent PayPal webhook events.
3. Conversational ledger: plain English in, a validated filter out, exact numbers
- Ask something like "past-due invoices over $1000" or "unpaid invoices from Germany". The LLM turns the question into a JSON filter spec, never SQL.
- The spec is validated by Pydantic against an allow-list of fields, operators per field type, status values and date formats, with at most 10 conditions and a row limit of 500 or less. If the model's output fails validation, a deterministic rule-based parser handles the question instead, and the UI shows which parser was used.
- If the question names a currency (
$,€,£, or a word or code), amount conditions are limited to that currency. Currencies are never converted or mixed. - The AG Grid table updates to show the matching rows. The summary sentence (count, totals per currency, number past due, maximum days late, clients) is computed exactly from those rows in code. The LLM never writes a number in it. The filter that was applied appears as badges, so you can see how your question was read.
Also built in
- Current UI: a sticky nav that tracks the section you are on; plain-language status toasts (success, loading, warning, error) that say what happened and what to do next, with technical details behind a Details toggle; an installable PWA with an Install app button that uses the browser's install prompt and explains Share → Add to Home Screen on iOS; and two seeded demo disputes, so the Disputes page is ready on first load.
- A dashboard with KPI cards: outstanding, overdue, paid this month and open disputes, each totalled per currency from the stored data.
- Demo controls for judges: a dev clock (+1, +3 or +7 days) to watch invoices change state, plus simulated payment and dispute webhooks that go through the real webhook handler in mock mode.
- The sidebar shows whether PayPal is running in Sandbox or Demo (mock) mode and whether a model or the rules fallback is active, so the demo always shows which mode it is in.
How we built it
Backend: Python, FastAPI, LangGraph, SQLAlchemy 2, Pydantic v2, httpx
paypal.pydefines aPayPalClientprotocol with two implementations:SandboxPayPalClient: OAuth2 client-credentials with a cached token (refreshed 60 s before it expires); exponential backoff with jitter on 429 and 5xx responses that honoursRetry-After; a freshPayPal-Request-Idon every call so retries are idempotent; multipartprovide-evidence; webhook signature verification via/v1/notifications/verify-webhook-signature.MockPayPalClient: an in-memory client that mirrors PayPal's response shapes (INV2-…ids, dispute objects withdisputed_transactions,seller_response_due_date, and so on). The app switches to sandbox automatically when both credentials are set.
state_machine.pyholds the invoice lifecycle as pure functions, which makes it easy to test.agents.pycontains the two LangGraphStateGraphs. Each node records itself in a trace, and the UI shows that trace.filters.pycontains the FilterSpec schema, the validator, the deterministic parser, currency enforcement, and the exact summarizer.evidence_search.pydefines anEvidenceSearchinterface with SQLite FTS5 and Postgres full-text implementations. It is built so a hybrid search backend can be swapped in later.llm.pypicks a provider automatically: withANTHROPIC_API_KEYit calls Claude through the official Anthropic SDK using tool-use structured output; optionally, withOPENAI_API_KEYinstead, any OpenAI-compatible endpoint in JSON mode; with no key, nothing. If a call fails or no key is set it returnsNone, and every caller has a deterministic fallback, so the app works with no model at all.- Webhooks:
POST /api/webhooks/paypalverifies the signature, de-duplicates by event ID, then routesINVOICING.INVOICE.PAID,PAYMENT.CAPTURE.COMPLETEDandCUSTOMER.DISPUTE.CREATED. - Database: SQLite by default. Setting
DATABASE_URLswitches to Postgres (for example Supabase). The demo runs on SQLite.
Frontend: Next.js 14 (App Router), TypeScript, React 18, AG Grid Community (Quartz theme)
- Workspace pages: Invoices (
/app), Disputes (/disputes) and Ask the ledger (/ledger), plus a sidebar showing live environment status. - Public pages: a landing page (
/), a plain-language learning page on what the AI decides versus what code enforces (/how-it-works), and a clearly labelled demo login (/login) with no real authentication; "Continue to demo" opens/app, so judges are never blocked. - Installable PWA: web app manifest, generated monochrome-and-lime icons, and a service worker that caches only the app shell (never API responses). Chrome reports no installability errors.
- AG Grid tables with custom cell renderers for status badges, country flags, days late and per-row actions ("Send via PayPal", " Draft reminder").
Quality and tooling
- 56 automated pytest tests cover the state machine, filter validation (including a SQL-injection-shaped field name being rejected), currency handling, OAuth plus backoff (using
httpx.MockTransport), the webhook signature request, the full invoice flow, webhook de-duplication, the dispute package and the guard against double submission, Sync polling, exact KPI totals, the self-healing mock after a restart, and the plain-language error mapper. Guardrails are tested too. All 56 pass. docker compose up --build, or one script each for backend, frontend and tests.
PayPal APIs used
| Area | Endpoint / event | Used for |
|---|---|---|
| OAuth 2.0 | POST /v1/oauth2/token (client credentials) |
Access token, cached and refreshed |
| Invoicing v2 | POST /v2/invoicing/invoices |
Create invoice (invoicer, recipient, line item, due date) |
| Invoicing v2 | POST /v2/invoicing/invoices/{id}/send |
Send invoice to the client |
| Invoicing v2 | GET /v2/invoicing/invoices/{id} |
Sync: detect PAID / MARKED_AS_PAID / CANCELLED; live read-through |
| Disputes v1 | GET /v1/customer/disputes |
Sync: discover new disputes |
| Disputes v1 | GET /v1/customer/disputes/{id} |
Fetch full dispute details and buyer messages |
| Disputes v1 | POST /v1/customer/disputes/{id}/provide-evidence |
Submit the defense, only after the user approves |
| Webhooks | POST /v1/notifications/verify-webhook-signature |
Verify every incoming webhook (sandbox mode) |
| Webhook events | INVOICING.INVOICE.PAID, PAYMENT.CAPTURE.COMPLETED, CUSTOMER.DISPUTE.CREATED |
Payment detection, dispute intake |
| Headers | PayPal-Request-Id |
Idempotency on every API call |
AI tools used and how
Inside the product
- LLM: Claude (
claude-sonnet-5-5) through the Anthropic SDK with tool-use structured output. An OpenAI-compatible endpoint is supported as an optional alternative. It is used in these places:- scoring the sentiment of a client's recent messages (reminder agent);
- deciding the next reminder action, tone and suggested fee, which code guardrails then bound (reminder agent);
- drafting the reminder email from the guarded decision (reminder agent);
- ranking evidence by relevance and flagging gaps (dispute agent; unknown ids are dropped and scores clamped to 0–1);
- writing the dispute statement from the retrieved evidence only, with citations (dispute agent);
- turning a ledger question into a JSON FilterSpec (conversational ledger).
- LangGraph runs the two agents as explicit state graphs (5 nodes and 4 nodes), so every run produces a trace you can inspect.
- Guardrails, by design:
- The model never decides money. Late fees, totals, counts and days overdue are all computed in code.
- The model never writes SQL. Its output is a spec checked against an allow-list.
- The model never sends anything. Reminders stay drafts, and dispute evidence needs an explicit approve-and-confirm.
- Every model call has a deterministic fallback, so a timeout or a missing key never breaks the workflow.
During development
- Cursor and Grok Bot (AI coding assistants) were used while building the code and docs.
- ElevenLabs (voices for the demo video), Google Flow with Veo (video shots for the demo video) and Higgsfield (character and mascot images for the demo video).
- Claude is the model used at runtime inside the product (see above); it is not used to compute any amounts.
Challenges we ran into
- Webhooks need a public URL. Local and sandbox testing often has none. I added Sync with PayPal, which polls invoices and disputes and feeds the results through the same handlers the webhooks use, so both paths behave the same way.
- Time-dependent behaviour is hard to demo and test. Overdue states depend on the date, so I built a persistent dev clock (an offset in the settings table) that the state machine, the summaries and the UI all read from.
- Stopping the AI from making up numbers. A financial answer that is "probably right" is useless, so the ledger follows one rule: the LLM writes the filter and code computes the answer. The filter is checked against the schema, a deterministic parser takes over if the check fails, and totals come only from the matching rows.
- Mixed currencies. "Over $1000" must not match a €6,500 invoice. I added currency detection and enforcement, and totals are always reported per currency, never converted.
- Parsing edge cases. "Overdue more than 5 days" must not become "amount > 5", and "under 1k" must mean 1,000. Both cases have regression tests.
- Sandbox details. PayPal invoice numbers must be unique per account and survive local database reseeds, so sandbox numbers get a random suffix. Leaving the invoicer email blank lets PayPal use the REST app's business account.
- Retries without double side effects. Exponential backoff plus
PayPal-Request-Idhandles retries, webhook de-duplication by event ID handles redelivered events, and a server-side guard stops dispute evidence from being submitted twice.
Accomplishments that we are proud of
- Human-in-the-loop is enforced in code, not just promised. The reminder approve endpoint cannot send email, and
provide-evidenceis reachable only through the explicit approval endpoint. - A dispute defense that cites its sources: every claim in the statement points to an evidence ID shown in the timeline.
- A conversational ledger whose numbers you can trust: the applied filter is shown as badges, and the parser used (LLM or fallback) is labelled.
- The whole product runs with no credentials and no model (mock PayPal plus deterministic fallbacks), and the same code moves to the real sandbox when you add keys.
- 56 passing tests covering the risky parts: money, state, webhooks and PayPal retries.
What we learned
- Agentic does not have to mean autonomous. The most useful setup was agents that gather, reason and draft, with explicit graphs and visible traces, and a person who decides.
- Put structure between the LLM and anything that matters: JSON specs, allow-lists, deterministic fallbacks and exact computation.
- How PayPal's Invoicing, Disputes and Webhooks APIs fit together, and the operational details that matter: OAuth token lifetimes, idempotency keys, signature verification, and how disputes link back to invoices through
disputed_transactions. - Designing for a solo freelancer means fewer screens and clearer states. Every page says what will happen and what will not happen without your approval.
What is next (planned, not yet built)
- Hybrid evidence search (keyword plus semantic, for example Elastic) behind the existing
EvidenceSearchinterface. - Evidence ingestion and file attachments: uploading contracts and delivery PDFs, and attaching them to
provide-evidence(the client already accepts files, but the app does not upload any yet). - More dispute lifecycle events (updates, resolution) and response-deadline alerts.
- Accounts and multi-tenancy: today the app is single-user;
/loginis a demo screen with no real authentication. - Optional one-click sending of approved reminders through the user's own email, still behind explicit approval.
- Move the hosted demo from SQLite to Postgres/Supabase so data persists.
- Side project: packaging the PayPal layer (OAuth, retries, idempotency, webhook verification, a mock that behaves like the sandbox) as an easy connector for African developers building on PayPal.
Built With
- ag-grid
- anthropic
- claude
- docker
- fastapi
- heroui
- httpx
- langgraph
- next.js
- oauth2
- paypal
- paypal-disputes-api
- paypal-invoicing-api
- paypal-webhooks
- postgresql
- pydantic
- pytest
- python
- react
- render
- sqlalchemy
- sqlite
- typescript