🤠 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:

  1. 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.
  2. 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_context and guarantees capture upon buyer approval via both redirect capture (/payment/success) and cryptographic CHECKOUT.ORDER.APPROVED webhook 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.COMPLETED using 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, or NO_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).
  • 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:

  1. 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.
  2. 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 unique PayPal-Request-Id headers to guarantee idempotency.
  3. Cryptographic Webhook Ingestion & Signature Verification

    • Incoming events (PAYMENT.CAPTURE.COMPLETED, CHECKOUT.ORDER.APPROVED, PAYOUTSBATCH.SUCCESS) are verified using PayPal's POST /v1/notifications/verify-webhook-signature endpoint.
    • Validated captures automatically update the ledger, reset the debtor's Heat Score to zero, and broadcast real-time celebration 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 in purchase_units. We do not claim to be an independent non-custodial bank.


🧗 Challenges We Faced

  1. The PayPal Two-Step Capture Trap: Early in testing, sandbox orders showed APPROVED status, but the balances didn't reflect settled funds. We learned that intent: "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.
  2. 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).
  3. 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.
  4. 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 (/pause or /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

Share this project:

Updates

Submission history