Inspiration
A freelancer can deliver excellent work and still spend evenings chasing an invoice. The next reminder is often written without understanding what is blocking payment. A client may have lost a link, need an invoice detail, disagree with the scope, or be waiting for a payment run. Each situation deserves a different response.
We built InvoiceRescue AI to put that context into the collection workflow. The goal is to help independent professionals act with clarity while preserving the client relationship.
What it does
InvoiceRescue AI brings together a PayPal invoice, a customer reply, an AI explanation, and a merchant-approved next step.
The merchant creates or synchronizes USD invoices from PayPal Sandbox, then pastes a customer message. Payment Blocker Intelligence classifies the reply into one of eight categories, quotes supporting evidence, and prepares a concise message draft. A deterministic policy maps the classification to a permitted action.
The merchant reviews and edits the recommendation before approving it. Supported outcomes include a PayPal reminder, sharing the existing invoice payment link through a reminder, saving an information-request draft, recording a payment promise, and pausing follow-ups for human review.
PayPal remains the source of invoice payment status. The application rechecks that status before an outgoing reminder. Verified PayPal webhooks reconcile invoice state and deduplicate events. Reconciliation blocks pending reminders when the fetched state is settled, closed, or payment-pending. A real hosted Sandbox payment updated the invoice to Paid and zero outstanding without a manual PayPal refresh.
A separate interactive demo contains synthetic invoices and preset analyses. It is clearly labeled, can be reset, and keeps changes in the visitor's browser.
How we built it
The application uses Next.js App Router, TypeScript, Tailwind CSS, a shadcn-style button component, and Lucide icons. Supabase provides PostgreSQL and merchant authentication. Ownership-based row-level security restricts browser reads, while server authorization gates writes and internal database functions.
PayPal Invoicing REST API v2 supplies real Sandbox invoice creation, retrieval, synchronization, sending, and reminder operations. The webhook handler uses PayPal signature verification before processing events. Real Sandbox creation, sending, and payment events have passed signature verification and processing on the hosted application. The first creation event exposed the nested invoice payload shape, which was corrected and added to regression tests before the payment test.
AI analysis uses the OpenAI Responses API format with a strict JSON schema and Zod validation. The hosted build connects to Vercel AI Gateway using openai/gpt-4.1-mini with request-scoped OIDC authentication. A real hosted analysis and database save have been verified. The provider endpoint and model remain configurable for local development. Supporting quotes must exactly match the supplied message, and backend code controls the available actions.
Codex assisted with implementation, debugging, test creation, and documentation. Runtime AI analyzes customer messages and prepares recommendations. Merchant approval remains part of the product workflow.
Challenges we ran into
Payment events require careful interpretation. An invoice-paid event can involve partial or pending payment, so the handler fetches the current invoice before deciding what changed. Our first real notification also revealed that PayPal nests the invoice inside the event resource. Testing the hosted listener exposed that mismatch before the final payment check.
Retries and concurrent clicks create a second challenge. We persist operation IDs, payload hashes, approval claims, reminder budgets, and uncertain outcomes in PostgreSQL. Database functions use locks to keep repeated approvals and event deliveries consistent.
Moving from local development to a hosted app introduced a provider boundary: the local AI proxy could not be reached by a cloud server. We connected the hosted app to Vercel AI Gateway, verified a model eligible for the free-credit tier, and used short-lived Vercel identity tokens to authenticate requests.
Accomplishments that we're proud of
We connected a working interface to PayPal Sandbox invoice creation and real AI analysis, with exact supporting evidence visible to the merchant. We completed a USD 1.00 Sandbox buyer payment and verified that a signed PayPal payment notification automatically reconciled the hosted invoice to Paid with zero outstanding and further reminders blocked. The application makes a recommendation reviewable before it can produce an external action.
We also built and exercised policy tests, webhook boundary tests, entry-point access tests, and rollback-only database regression checks. The tests cover pending and partial payments, payment promises, invented evidence, malicious links, duplicate claims, uncertain outcomes, and stale reconciliation.
The interface presents synthetic demo behavior and connected Sandbox behavior explicitly, helping a reviewer understand which service produced each result.
What we learned
A collection assistant needs to reason about uncertainty in both conversation and payment processing. A client's claim that they paid should trigger reconciliation. A request timeout should remain unresolved until its outcome can be checked. A promise to pay needs a calendar date and a policy that respects it.
AI is most helpful here when its explanation is inspectable and its proposed action passes through a small, explicit set of business rules.
What's next for InvoiceRescue AI
We plan to add secure mailbox connections, merchant onboarding, additional currencies, and a richer evaluation set for payment-blocker classification. We also want to test the workflow with freelancers and measure time spent on follow-ups and invoice resolution, using consented data and clearly defined baselines.
Built With
- next.js
- openai
- paypal
- postgresql
- react
- supabase
- typescript
- vercel