🤠 TripSheriff AI - Autonomous Group Travel Treasury & Debt Enforcement Agent
"Group trips make memories. Collecting the money afterwards destroys friendships. TripSheriff AI saves both."
💡 Inspiration
Picture this: You and five friends return from a dream vacation in Bali. You fronted $2,400 on your personal credit card for the villa deposit, rental scooters, and a sunset seafood dinner.
Two weeks later, the vacation is over, but the awkward collection nightmare begins:
- Spreadsheets with rounding drift and disputed cocktail splits.
- Group chats filled with passive-aggressive "hey guys, don't forget to pay me back" texts.
- One friend who "forgot to link their bank account" while actively posting stories from another expensive brunch.
Financial consumer studies consistently reveal that over 35% of adults experience damaged friendships or unpaid debts due to group travel expenses. Traditional split apps (Splitwise, etc.) are passive ledgers - they tell you who owes what, but they cannot collect, they cannot disburse, and they leave all the awkward social friction squarely on your shoulders.
We asked ourselves: What if an autonomous AI agent took full ownership of the group treasury? An agent that reads crumpled paper bills with vision models, maintains an integer-cent double-entry ledger, generates 1-click PayPal checkout links, disburses reimbursements via PayPal Batch Payouts, and uses consensual comedic psychological escalation (Polite Concierge → Passive-Aggressive Roommate → Disappointed Parent) to eliminate deadbeat debt friction forever.
Thus, TripSheriff AI was born.
🚀 What It Does
TripSheriff AI operates across two synchronized interfaces:
- Interactive Web Simulator & Master Treasury Dashboard: Built specifically so hackathon judges and organizers can test the entire agentic loop, trigger simulated expenses, test PayPal sandbox checkouts, and execute batch payouts in one window with zero setup.
- Live Group Chat Assistant: Communicates naturally in conversation, processes photo receipts, and drops 1-click PayPal buttons directly into chat.
Core Capabilities:
- 🧾 Multimodal Receipt OCR & Itemizer: Snap a crumpled paper restaurant receipt → AI extracts vendor, items, tax, and tip → renders interactive claim buttons so friends can tap what they ate or drank.
- 🧮 Double-Entry Integer-Cent Ledger: Zero rounding drift. Simplifies an O(N²) debt matrix into at most N-1 settlement transactions using a Bipartite Minimum Cash Flow algorithm.
- 💳 PayPal Orders API (v2) with Two-Step Capture: Generates 1-click checkout links with
experience_contextand guarantees capture upon buyer approval via both redirect capture (/payment/success) and cryptographicCHECKOUT.ORDER.APPROVEDwebhook listeners. - 💸 PayPal Batch Payouts API (v1): Reimburses trip organizers or settles net creditor balances in seconds with Human-in-the-Loop confirmation.
- 🔔 Cryptographic Real-Time Webhooks: Listens to
PAYMENT.CAPTURE.COMPLETEDusing PayPal signature verification (verify-webhook-signature) to instantly clear debts and trigger celebratory confetti. - 🎭 5-Tier Consensual Escalating Personality Matrix: Opt-in comedic escalation (
MILD,SPICY, orNO_ROAST) that recovers money through social comedy rather than hostility:- Tier 1: Polite Concierge (0-12h): "Hey Alex! Quick link for your $80 villa split 🏖️ Hope you're having fun!"
- Tier 2: Passive-Aggressive Roommate (12-24h): "Must be nice watching the sunset while Sarah fronts your bed... 👀"
- Tier 3: Disappointed Parent (24-48h): "Alex beta, is this how we raised you? Leaving Sarah to carry your hotel costs while you order craft cocktails?"
- Tier 4: Public Roast Card (48-72h): Generates a dynamic meme card in chat ("WANTED: Alex | Bounty: $80 | Crime: Ordering Wagyu on someone else's credit card").
- Tier 5: Itinerary Embargo (>72h): Applies social group sanctions ("Trip sanction: Alex demoted to the pull-out couch until the $80 clears").
📐 Mathematical Formulation & Financial Core
To guarantee financial integrity, TripSheriff completely bans floating-point numbers in its database and calculation engine. All financial states are stored strictly as integer cents:
$$ \mathrm{amount_cents} \in \mathbb{Z}^{+} $$
1. Bipartite Minimum Cash Flow Debt Simplification
In a group of n travelers, arbitrary splits produce up to n(n-1) bilateral debt paths. TripSheriff reduces this to at most n-1 net transactions.
For each member i, the net balance (Delta i) is computed from all credits (C) and debits (D):
$$ \Delta_i = \sum C_i - \sum D_i $$
$$ \sum_{i=1}^{n} \Delta_i = 0 $$
Members are partitioned into:
- Creditors: Members with a positive net balance.
- Debtors: Members with a negative net balance.
A greedy bipartite matching algorithm iteratively pairs the maximum debtor with the maximum creditor:
$$ T_{j \rightarrow i} = \min(-\Delta_j, \Delta_i) $$
Updating the debtor's and creditor's balances after each transaction:
$$ \Delta_j \leftarrow \Delta_j + T_{j \rightarrow i} $$
$$ \Delta_i \leftarrow \Delta_i - T_{j \rightarrow i} $$
until all balances reach zero.
2. Proportional Tax & Tip Attribution
When splitting itemized restaurant receipts, flat tax/tip splits unfairly penalize non-drinkers. TripSheriff allocates tax and tip strictly in proportion to claimed item subtotal:
Tax allocation formula:
Tax(i) = round(
Tax(total) × (Subtotal(i) / Subtotal(total))
)
Any remainder-cent discrepancy is calculated as:
Delta = Tax(total) - Sum(Tax(i))
This discrepancy is deterministically assigned to the highest subtotal claimant, guaranteeing that:
Final receipt allocation:
Sum( Subtotal(i) + Tax(i) + Tip(i) ) = Total(receipt)
🏗️ How We Built It
We designed TripSheriff as a high-reliability, microservice-oriented architecture:
┌──────────────────────────────┐
│ Incoming Triggers │
├──────────────┬───────────────┤
│ Chat Gateway │ Web Simulator │
└──────┬───────┴───────┬───────┘
│ │
▼ ▼
┌───────────────────────────────────┐
│ Java 21 Spring Boot Backend │
│ (Double-Entry Integer Ledger) │
└──────┬─────────────────────┬──────┘
│ │
┌───────────────┘ └────────────────┐
▼ ▼
┌───────────────────────────┐ ┌───────────────────────────┐
│ Python AI Microservice │ │ PayPal Sandbox Suite │
│ • Gemini/Groq Tool-Loop │ │ • Orders API (v2) Capture │
│ • 5-Tier Personality │ │ • Batch Payouts API (v1) │
│ • Multimodal Receipt OCR│ │ • Webhook Verification │
└───────────────────────────┘ └──────────────┬────────────┘
│
▼
┌──────────────────────────┐
│ AG Grid Travel Portal │
│ (Live Real-Time Updates) │
└──────────────────────────┘
- Core Financial Backend (Java 21, Spring Boot 3.4):
- Domain-driven package-by-feature structure (
trip,member,expense,ledger,payment,payout,webhook). - Spring Data JPA with integer-cent normalization and pessimistic concurrency locking.
- H2 database for zero-config evaluation (seamlessly swappable to PostgreSQL via environment variable).
- Domain-driven package-by-feature structure (
- AI Intelligence & Vision Microservice (Python 3.11, FastAPI):
- Multimodal Receipt OCR: Google Gemini 2.0 Flash Vision and Groq Vision extracting structured JSON with bounding line items.
- Agentic Intent Classifier: Translates natural language group chat messages into structured tool calls (
LOG_EXPENSE,CHECK_BALANCES,DISPUTE_OR_PAUSE,PROPOSE_BATCH_PAYOUT). - Dynamic Escalation Generator: Calibrated system prompts executing the 5 comedic voices while passing through a strict safety/moderation filter.
- Frontend Simulator & Dashboard (React 19, Vite, Tailwind CSS, AG Grid):
- Built with AG Grid Community for high-performance sorting, filtering, and grouping of trip transactions.
- Interactive Web Simulator allowing instant testing of time-warps (
+24h), expenses, and PayPal drawers without needing a mobile device.
⚡ PayPal Developer Platform Deep Dive
We integrated three flagship PayPal developer capabilities:
PayPal Orders API (v2) - Intent: CAPTURE
- Creates orders with customized
payment_source.paypal.experience_context(user_action: "PAY_NOW"). - Embeds tracking metadata inside
purchase_units[0].custom_id(trip_id|debtor_id|expense_id). - The Two-Step Capture Mechanics: We strictly honor the PayPal capture rule: buyer approval does not transfer funds until our backend executes
POST /v2/checkout/orders/{id}/capture. We provide dual paths: instant redirect capture and secondary webhook capture fallback.
- Creates orders with customized
PayPal Batch Payouts API (v1)
- When a trip concludes, the organizer approves a single-click settlement payout.
- Disburses funds from pooled accounts to multiple member PayPal emails in one API call (
POST /v1/payments/payouts) with uniquePayPal-Request-Idheaders to guarantee idempotency.
Cryptographic Webhook Ingestion & Signature Verification
- Incoming events (
PAYMENT.CAPTURE.COMPLETED,CHECKOUT.ORDER.APPROVED,PAYOUTSBATCH.SUCCESS) are verified using PayPal'sPOST /v1/notifications/verify-webhook-signatureendpoint. - Validated captures automatically update the ledger, reset the debtor's Heat Score to zero, and broadcast real-time celebration events.
- Incoming events (
Honest Custody & Platform Routing Disclosure:
In this hackathon prototype, incoming payments are pooled into a sandbox platform proxy and disbursed using Batch Payouts. In commercial production, multi-party routing would be implemented using PayPal Complete Payments / PayPal Commerce Platform (Marketplace Payee Routing) with custom payee declarations inpurchase_units. We do not claim to be an independent non-custodial bank.
🧗 Challenges We Faced
- The PayPal Two-Step Capture Trap: Early in testing, sandbox orders showed
APPROVEDstatus, but the balances didn't reflect settled funds. We learned thatintent: "CAPTURE"requires the server to actively trigger the capture call. We engineered a resilient dual-path capture system (redirect callback + automated webhook fallback) so money is never left in limbo. - Eliminating Rounding Drift: Dividing $100.00 three ways yields $33.3333... If represented as floats, repeated splits generate lost cents. By storing pure integer cents and designing a deterministic remainder-cent distribution algorithm, our ledger balances to the exact penny (10000 = 3334 + 3333 + 3333).
- AI Latency in Conversational Commerce: LLM multi-step routing can take 5-10 seconds if cold-started. We solved this by using Groq LPU inference for sub-second intent classification (under 400ms) with Google Gemini handling deep multimodal receipt parsing.
- Balancing Comedy and Safety: An escalating debt collector agent can easily cross into harassment if unconstrained. We instituted explicit opt-in consent tiers (
MILD,SPICY,NO_ROAST), an instant opt-out command (/pauseor/dispute), and an automated content moderation filter that bans genuine threats, slurs, or vulgarity.
🏆 Accomplishments We're Proud Of
- 111 Passing Automated Tests: 79 automated Python tests and 32 Java Spring Boot integration tests with 100% mathematical split balance and zero failures.
- True Agentic Commerce: Our agent doesn't just chat - it evaluates overdue debt aging, calculates net balances, invokes PayPal Orders tools, and requests Human-in-the-Loop approvals for payouts.
- The "Disappointed Parent" Roast Voice: Turning the most awkward social experience into something friends actually laugh at in group chats.
- Zero-Friction Judge Simulator: Eliminating 100% of the barrier to entry by providing a rich, split-screen web simulator so anyone can evaluate the project in 60 seconds without configuring Telegram bots or phone numbers.
📚 What We Learned
- How modern PayPal Orders v2 and Batch Payouts v1 interact to create a complete bidirectional payment lifecycle (inbound collections + outbound disbursements).
- How to enforce mathematical invariants across distributed multi-language services (Java backend ↔ Python AI) using contract-locked JSON schemas.
- How to design agentic loops with Human-in-the-Loop checkpoints so autonomous financial agents remain safe, compliant, and under user control.
🔮 What's Next for TripSheriff AI
- PayPal Commerce Platform Marketplace Payee Routing: Upgrading to direct seller/receiver splits without platform-mediated escrow.
- Live Telegram & WhatsApp Bot Deployment: Expanding the existing webhooks into fully live multi-platform chat integrations.
- Multi-Currency Real-Time FX Settlements: Allowing an American organizer to settle in USD while an international traveler pays in EUR or INR via PayPal multi-currency conversion.
👥 Built With:
- PayPal Developer Platform (Orders API v2, Batch Payouts API v1, Webhooks API)
- Java 21 & Spring Boot 3.4
- Python 3.11 & FastAPI
- Google Gemini 2.0 Flash Vision & Groq
- React 19, TypeScript, Tailwind CSS, & AG Grid
Built With
- docker
- fastapi
- google-gemini-api
- groq
- java
- node.js
- paypal-orders-api
- paypal-payouts-api
- paypal-webhooks-api
- postgresql
- python
- react
- spring-boot
- tailwind
- telegram
- typescript