Inspiration

Getting paid is not the end of a freelancer's job. It's the start of a to-do list nobody reminds you about: set money aside for taxes, follow up with the clients who haven't paid, and, in Mexico, issue a CFDI, the tax invoice stamped under the rules of the tax authority (SAT).

Most finance tools wait for you to remember all of this. We wanted the opposite: an AI that makes the first move when you get paid, but never acts without your approval.

We also talked with two freelancers. With clients in Mexico, they prefer bank transfers to avoid fees, so we refocused on the case where PayPal shines: Mexican freelancers paid in USD by clients abroad.

What it does

A client in Texas pays your USD invoice:

  1. PayPal notifies the app through a webhook, and the invoice turns to Paid on its own.
  2. The copilot speaks first. It looks at the payment and proposes the next step, like setting part of it aside for taxes, and asks whether you need a CFDI to report the income.
  3. You stay in control. Every proposal arrives as an approval card. Nothing changes until you press Approve.

Also:

  • Chat with your money in English or Spanish: "Who owes me money?", "When did Test Buyer pay me?"
  • PayPal invoices in USD or MXN: create, send, remind and cancel from the chat or the Invoices page.
  • CFDI 4.0 in USD for clients abroad: you choose the VAT rate and the country, and the app adds the exchange rate.
  • CFDI 4.0 in MXN for clients in Mexico: they fill in their tax details once through a private link in Spanish.
  • Savings buckets (Personal mode) and Review all with AI: several payments waiting become one ticket with checkboxes and the AI's recommendation.
  • A 14-step guided tour on the first visit.

How we built it

  • Frontend: React 19, TypeScript, Vite, Tailwind CSS 4.
  • Backend: Node.js, Express 5, TypeScript, Zod.
  • PayPal: Invoicing API v2, Transaction Search through the official @paypal/paypal-server-sdk, and webhooks with signature verification. All in sandbox.
  • AI: Claude Sonnet 5.5 (Anthropic API) with tool use and prompt caching.
  • Tax invoices: Facturama sandbox (CFDI 4.0), with the exchange rate from Banxico or an ECB reference.
  • Data and hosting: Neon Postgres and Render. Live updates reach the browser through Server-Sent Events.

The approval rule lives in the server, not just in the prompt. Tools that change something (create, send or cancel invoices, save tax info, issue a CFDI, change savings) are never executed when the model calls them. They become approval cards, and they only run when the user approves.

Challenges we ran into

  • Making the AI proactive without making it noisy. When a payment arrives, the copilot has to say something useful once, not compete with the guided tour. We turned the rule-based guide off by default and let the copilot lead.
  • What must always appear can't depend on the model. Sometimes Claude proposed cards without writing a message, or skipped asking about the CFDI. Now the app itself adds that question after the cards.
  • CFDI in a foreign currency. The rules for clients abroad differ (generic foreign tax ID, export code, exchange rate field). The app never decides the VAT rate: whether 0% applies depends on the service, so the user chooses.
  • Judges can't pay an invoice. The "AI speaks first" moment needs a real payment, so we built the Review all with AI ticket, which judges can try with payments that are already waiting.
  • Free hosting wipes the disk on every restart. We moved savings and tax data to Neon Postgres.

Accomplishments that we're proud of

  • A complete loop in sandbox: invoice in USD → client pays → Paid on its own → the copilot proposes the next steps → CFDI stamped in USD.
  • An AI that can read everything but cannot change anything without a human click.
  • Being honest about limits: we don't claim tax compliance, and the README lists what is still missing.

What we learned

  • Proactive AI is mostly a product question: when to speak and what to propose matters more than the model.
  • Anything that must always happen should be guaranteed by code, not by the prompt.
  • Validate early. Talking to freelancers changed our main use case.

What's next for VNV Copilot

  • Withholdings and more tax scenarios, reviewed by a tax professional.
  • Accounts, so each freelancer connects their own PayPal and tax certificates.
  • Other countries, by plugging in e-invoicing providers with each country's rules.

Built With

Share this project:

Updates

Submission history