About the project

Inspiration

Many freelancers in India build for clients overseas and get paid through PayPal. The work happens in milestones, but the money side is handled by hand. You finish a phase, send an invoice, and wait. The client goes quiet. Chasing them feels awkward. Meanwhile the deadline doesn't move, so you start the next phase anyway. Now you're funding your client's project, and anyone you've brought in (an illustrator, a tester) is waiting too.

Project tools track tasks. Payment tools track money. Nothing connects the two. We wanted a tool where getting paid is part of the plan.

What it does

Paid to Proceed is an AI back-office agent for freelancers who bill clients through PayPal.

  1. Contract → payment-gated plan. Upload the contract you already signed (PDF or text). Claude extracts milestones, amounts, acceptance criteria, task durations and subcontractor splits. It also flags payment risks, like a missing late fee or a review step with no deadline. The result is a Gantt timeline where every phase ends in a PayPal payment gate, and the next phase depends on that gate.
  2. Scope check before invoicing. When you submit a deliverable, Claude checks it against each acceptance criterion and shows the evidence. If something's missing, it says so before the client sees an invoice.
  3. Human-in-the-loop invoicing. The agent proposes the invoice, with a client-ready note, into an approval inbox. You edit and approve, and a real invoice is created and sent through PayPal Invoicing.
  4. Late payments re-plan the project. If the invoice goes overdue, the payment gate stays open, so the scheduling engine pushes every later phase right, compared against the original plan. The delivery date updates too. The cost of paying late is visible, not buried in a spreadsheet.
  5. A collections agent. Claude drafts reminders whose tone escalates from friendly to firm to final, without ever threatening or inventing late fees. After you approve, they're sent through PayPal's invoice reminder API.
  6. Payment → unlock → pay the team. When PayPal confirms the payment (by webhook, or by polling), the gate turns green, the next phase unlocks, and each subcontractor's contract share is proposed as a PayPal Payout.
  7. Ask your agent. A chat agent answers questions like "Who still owes me money, and has my team been paid?" using live PayPal data through the PayPal Agent Toolkit. Any action it suggests still goes to the approval inbox.

Nothing that moves money or emails a client happens without the freelancer's approval.

How we built it

  • Frontend: React + Vite, with the Bryntum Gantt for the timeline. Payment gates are real Gantt tasks with dependencies, so Bryntum's scheduling engine re-plans the project when a gate stays open. Baselines show the original plan as a ghost bar under each task.
  • Backend: Node.js + Express (TypeScript), with a small JSON store.
  • PayPal (sandbox):
    • Invoicing v2: generate the invoice number, create, send, remind, get status, and record a payment
    • Payouts v1: create a payout batch and track its status
    • Webhooks: INVOICING.INVOICE.PAID and PAYMENT.PAYOUTSBATCH.*, with signature verification and a 20-second polling fallback
    • PayPal Agent Toolkit (@paypal/agent-toolkit): read-only invoice, transaction and dispute tools for the chat agent
  • AI: Claude (claude-opus-5-5) through the official Anthropic TypeScript SDK:
    • PDF contract understanding, with structured outputs validated against a Zod schema
    • deliverable-vs-criteria scope checks
    • reminder drafting with tone escalation
    • a tool-using agent (the SDK's tool runner) over our own tools plus the PayPal Agent Toolkit. Tools that would move money can only propose an action into the inbox.
  • Hosting: Render.
  • Testing: an end-to-end script that runs the whole flow (contract → scope check → invoice → overdue → reminder → payment → payout → chat) against the real PayPal sandbox and Claude.

Challenges we ran into

  • Making the schedule respond to money. We had to model payment gates as tasks whose duration depends on the invoice state: projected, awaiting, overdue or paid. That way the Gantt engine, not our own code, pushes later phases.
  • Keeping the AI honest. The scope check is deliberately strict. In one test it refused to call the work "done" because the submission didn't prove the client had reviewed all six mockups. We kept that behaviour and added an "invoice anyway" override, so the human decides.
  • Safe agent design. We wanted a real agent, not just a chatbot, without letting it move money on its own. The solution was a proposal-and-approval inbox shared by every agent and chat action.
  • PayPal app permissions. Invoicing needs a feature flag on the sandbox app. The app now checks the granted scopes and tells you exactly which feature is missing.

Accomplishments that we're proud of

  • A full, working loop on the real PayPal sandbox: contract → plan → scope check → invoice → overdue → reminder → real client payment → unlock → payout.
  • A visual idea that's easy to grasp: a late payment visibly pushes the whole project back.
  • An agent that's useful and safe: it proposes, explains its reasoning, and waits for approval.

What we learned

  • How PayPal's Invoicing, Payouts, Webhooks and Agent Toolkit fit together into one money workflow.
  • That structured outputs plus strict prompts make an LLM a reliable checker, not just a writer.
  • That human-in-the-loop design is a feature users trust, not a limitation.

What's next for Paid to Proceed

  • Real accounts and multi-project dashboards for freelancers and small agencies.
  • Escrow-style deposits for new clients through PayPal Orders, and Pay Later messaging on invoices.
  • Contract-aware dispute help using PayPal Disputes.
  • Multi-currency invoicing and INR cash-flow forecasts for freelancers in India.

Built With

Share this project:

Updates

Submission history