DuePilot

An AI collections agent for freelancers: say who owes you, approve the card, and PayPal invoices, reminds, reconciles and pays contractors for you.

Comment

Inspiration

Freelancers and one-person businesses spend hours chasing payments: writing invoices, remembering who hasn't paid, sending awkward follow-ups and matching payments by hand. For solo workers billing clients across borders, a late invoice means a late rent payment. We wanted an assistant that doesn't just draft text but actually does the work through PayPal, while never moving money without the owner's say-so.

What it does

  • Natural-language invoicing: "Invoice Acme Corp [email protected] 450 USD for the logo work, net 7, remind them twice." The AI extracts client, email, amount, currency, terms and reminder count into a validated tool call.
  • Human-in-the-loop approval: every action that touches PayPal appears as an approval card. Nothing is created, sent or paid until you click Approve.
  • Real PayPal invoices: on approval DuePilot creates and sends a PayPal invoice and returns PayPal's hosted pay link.
  • Automatic follow-ups: the reminders you approved are scheduled and sent through PayPal's invoice-reminder API; the AI writes polite ad-hoc reminders on request.
  • Auto-reconciliation: PayPal's INVOICING.INVOICE.PAID webhook is signature-verified and de-duplicated, then the invoice flips to Paid and the cash-flow dashboard updates. A "Sync" button pulls status from PayPal as a fallback.
  • Contractor payouts: "Pay [email protected] 120 USD for illustrations" → approval → PayPal Payouts, with a hard per-payout cap.
  • Cash-flow answers: "Show unpaid invoices", "Cash flow summary".
  • ⚡ Autopilot (agentic commerce with a spending policy): standing rules let the agent send small invoices, reminders and high-confidence payment matches without a click, within a per-invoice limit and a daily cap. Payouts, cancellations and anything from a pasted email can never be automated. Rules are enforced in code, and every auto-action is audit-logged with the rule that allowed it.
  • Invoice from a pasted email: paste a client's message and Gemini turns it into an itemised PayPal invoice card. The email is treated as untrusted data, and payout/cancel tools are blocked in code for that turn, so prompt injection in an email can't move money.
  • Multi-line invoices: "3 banners at $150 + $60 rush fee" becomes separate PayPal line items, and the total is recomputed in code.
  • Payment matching with PayPal Transaction Search: finds money that arrived outside an invoice link (e.g. a direct transfer), matches it to the right open invoice with explained reasons, and, after approval, records the payment on PayPal so the invoice is marked paid.
  • Weekly cash-flow briefing: numbers are computed in code, and Gemini turns them into a 4-sentence summary with one-click next actions. It is only allowed to use the supplied figures.
  • Recurring invoices (retainers): "bill Kestrel $500 every month". Approve the schedule once, then each period's PayPal invoice is drafted automatically and follows your approval or Autopilot rules.
  • Quick payment requests (PayPal Orders v2): "request $40 from Sam" creates a PayPal checkout link. The payment is captured when the client returns, or by the verified webhook if they don't.
  • Reminders in the client's language: Gemini writes the reminder natively in Spanish, Hindi, German and so on, with an English summary on the approval card.
  • Scan-to-pay QR codes generated by PayPal for every unpaid invoice, and CSV export of invoices and the audit trail for accountants.
  • Client risk insights: "Who should I chase first?" ranks clients by average days to pay, late-payment rate and overdue balance. Reminder tone escalates politely for higher-risk clients.
  • Data grid (AG Grid Community) for invoices: sort, filter, pay links, PayPal status sync.
  • Estimated admin time saved KPI, so the impact is visible.
  • Audit log of every proposal, approval, PayPal call, webhook and error.
  • Voice input and a responsive UI that works on phones.
  • Keyless demo mode so anyone can try every flow instantly.

How we built it

Node.js + Express backend, vanilla JS frontend, JSON-file store. The agent loop sends the conversation plus a set of typed tool declarations (invoices, reminders, recurring invoices, payment requests, payouts, payment matching, insights and summaries) to Google Gemini 3.5 Flash (function calling). Tools that read data run immediately; tools that write only create pending actions. The approval endpoint is the only code path that calls PayPal's write APIs, and it uses a stable PayPal-Request-Id per action and step, so retries and double-clicks can never create duplicate invoices or payouts. The PayPal client handles OAuth token caching, retries on 429/5xx with the same idempotency key, and clear error messages. Webhooks are verified with PayPal's verify-webhook-signature API before any state changes. Hosted on Render.

PayPal APIs used

OAuth2 · Invoicing v2 (create, send, get, remind, cancel, record payment, QR code) · Orders v2 (create checkout, capture) · Transaction Search (reporting) · Payouts · Webhooks (verify-webhook-signature; INVOICING.INVOICE.PAID, INVOICING.INVOICE.CANCELLED, CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED). Sandbox only.

AI tools used and exactly how

  • Google Gemini 3.5 Flash via the Generative Language REST API with function calling. It (1) turns free-text requests into structured tool calls (e.g. create_invoice, send_reminder, schedule_recurring_invoice, request_payment, pay_contractor, reconcile_payments, client_insights, cash_flow_summary), (2) writes reminder messages, including in the client's language, and (3) summarizes tool results and writes the weekly briefing.
  • Guardrails outside the model: all tool arguments are schema-validated in code (email, amount > 0, currency whitelist, terms 0-90 days, ≤3 reminders, invoice cap 5,000, payout cap 500); invalid calls are returned to the model as errors.
  • Provider-agnostic: a one-method provider interface; a keyless deterministic demo provider emits the same tool calls when no API key is set (shown as "AI: demo" in the UI).
  • Browser Web Speech API for voice input.
  • Development: built with the help of an AI coding assistant (Claude Code by Anthropic) for code, tests and documentation. Claude is not used inside the running app; the app's AI is Google Gemini, as described above.

Challenges we ran into

Making an agent safe enough to touch money, and then safe enough to act on its own (Autopilot): we separated "propose" from "execute", enforced caps in code rather than in prompts, and designed idempotency keys so a retry after a network error never double-bills.

Accomplishments that we're proud of

A full loop (request → approval → PayPal invoice → client pays → verified webhook → reconciled dashboard) with tests covering the agent flow, guardrails, idempotent retries and webhook signature verification.

What we learned

PayPal's Invoicing, Orders, Payouts and Webhooks APIs; how to design tool-calling agents with human approval and code-enforced spending policies; why idempotency matters for payments.

What's next

Multi-user accounts and Postgres; payout webhook reconciliation; WhatsApp/email intake; smarter reminder timing based on each client's payment history; multi-currency cash-flow forecasting.

Try it

Share this project:

Updates

Submission history