TipPool

Guests tip by QR with PayPal or Venmo; AI turns house rules into an exact, explained split and checks the shift; one PayPal Payouts batch pays the whole team.

Comment

Inspiration

While researching how restaurants, bars and cafés handle tips, I kept finding the same gap: payments are automated everywhere else, but almost nothing automates what happens to the tips after the guest pays.

Tipped teams split money by hand at the end of every shift: a calculator, a spreadsheet, cash envelopes, bank transfers one by one. It's slow, it's error-prone, and the staff can't see how their share was worked out.

What it does

  • Tips in: guests scan one QR code and tip with PayPal or Venmo, in their own language (7 languages). Card-machine and cash tips are added at close-out, so the whole day's tips are shared.
  • Rules in plain words: the owner writes the house rules the way they'd say them ("bartenders get 20%, the rest goes to servers by hours"). AI reads them into structured rules and warns about anything that breaks tip law (US FLSA: managers can't take from the pool).
  • Who worked, without typing: staff clock in and out from their own private page; the close-out fills itself in. A photo of a paper schedule works too.
  • The split: exact cents, done in plain code (the AI never decides amounts). AI explains every person's share and checks the shift before any money moves: a flagged problem, a 15-hour shift, an unconfirmed payout address, a total far from normal.
  • Tips out: one PayPal Payouts batch pays the whole team to PayPal or Venmo, tracked live with webhooks; failed or unclaimed payouts can be reminded, taken back and sent again.
  • Payouts as Render Workflows: the riskiest step, moving money, runs as a durable Render Workflow. Sending and following the payout are separate tasks that retry on their own when PayPal or the network fails, always with the very same request, which PayPal never pays twice. The manager watches every step live on the payout page.
  • An agent that moves money, safely: "Close out tonight, add $40 cash and pay everyone" becomes a short plan the manager confirms once. Every step is checked again when it runs (the close-out check, the payout freeze, the owner's approval limit), and the AI can stop a payout but never start one on its own.
  • For real businesses: several locations, business accounts with managers and shift leads, owner controls (approval limit, emergency freeze), live board, smart alerts, interactive reports and CSV export.

How we built it

Django 5.2 and Python, PostgreSQL (Neon), plain HTML/CSS/JS. PayPal: Orders API v2 and the JS SDK v6 (PayPal and Venmo buttons), Payouts API (PayPal and Venmo recipients, cancel unclaimed), Reporting (balance check before paying) and webhooks with signature verification.

On Render: the website is a web service; payouts run on Render Workflows (a pay_shift run with send_payout and follow_payout tasks, each with its own retry policy); a Render Key Value store is the shared cache for rate limits and the live payout steps; and one Blueprint (render.yaml) creates all three and wires them together.

Reports, past shifts and the activity log are interactive tables built with AG Grid Community (search, sort, filter, totals of what's shown), under a strict Content-Security-Policy. 425 automated tests.

AI: what it does and how

  • AI service: the live demo runs on DeepSeek; Claude (Anthropic), Gemini, ChatGPT, Kimi or Mistral can be switched in from the app's Platform settings. Every service gets the same instructions and must answer in the same JSON schema, checked on arrival.
  • What the AI does: reads tip rules written in plain words (with legal warnings); reads a photo of the schedule to fill in who worked; explains each person's share; reviews each shift before payout; answers questions from the business's own numbers and proposes actions (close out, add tips, pay through PayPal Payouts, fix payouts) that the manager confirms.
  • Guardrails: amounts are calculated in code, never by the AI; every action needs the manager's confirmation through a signed, single-use token that pins the exact split shown; text written by staff or guests is treated as data, never instructions; daily AI limits, with a built-in assistant taking over if the AI is unavailable.

Challenges we ran into

Money has to be right every time: payouts that can never go out twice (fixed batch ids, unclear answers checked with PayPal instead of re-sent), refunds and chargebacks arriving after a shift was paid, webhooks that may be late or repeated, and an AI agent that must never move money nobody confirmed. Moving the payout into a Render Workflow meant every step had to be safe to retry: a retry sends the very same request, a clear "no" from PayPal undoes the payout, and a payout freeze stops a run before it sends.

Accomplishments that we're proud of

A full loop that really runs on the PayPal sandbox, from a guest's tip to the whole team paid, with every share explained. And a security pass: business isolation, encrypted secrets, two-step sign-in, a strict Content-Security-Policy, and payouts that only go to addresses their owners confirmed.

What we learned

Payments code is mostly about the unhappy paths: unclear answers, retries, refunds after the fact. And AI is most useful when it explains and checks, while the money math stays in plain code.

What's next for TipPool

Going live with real PayPal money for a first restaurant, POS integrations so card tips arrive by themselves, payroll exports, and more languages.

TipPool is a hackathon demo today: it runs only on the PayPal sandbox (test money), and no real business uses it yet. Going live would need a registered business, agreements with each venue, a live PayPal account approved for payouts, and checks against local tip and payroll-tax law.

Built With

Share this project:

Updates

Submission history