Inspiration

Across the globe, millions of immigrants, expatriates, and professionals living abroad regularly support aging parents or relatives back home. When an urgent household repair occurs—such as a plumbing leak, an electrical short, or an appliance failure—coordinating reliable maintenance across time zones is stressful. Families often encounter opaque pricing, fears of unauthorized charges, and dispute headaches. Meanwhile, independent artisans and domestic gig workers often face delayed disbursements and platform deductions with limited transparency into how service fees are split.

We built UniServ Pay to address this cross-border care gap. UniServ Pay extends a cooperative home-services platform by uniting PayPal Sandbox (for secure cross-border authorization holds and batched split disbursements) with Google Gemini AI (for multimodal repair triage and autonomous settlement auditing) and an open co-op treasury ledger.


What it does

UniServ Pay enables family members abroad to book, authorize, and settle home repairs transparently:

  1. Multimodal AI Smart Triage: The user describes the issue and attaches a photo. Google Gemini (gemini-3.5-flash-lite) parses the request into a structured diagnostic schema (trade_id, urgency, likely_parts, price_range_inr, and customer/worker dispatch summaries).
  2. Guarded PayPal Authorization Hold: The buyer pre-authorizes an estimated hold in USD via PayPal Sandbox (with a 25% contingency buffer) using a transparent conversion rate ($\$1\text{ USD} = 85\text{ INR}$). Funds remain held—not captured—until the job is complete.
  3. Server-Stamped Milestones: As the artisan performs the work (start, pause_parts, resume, extra_work, complete), each milestone is validated and timestamped on the server, tracking deterministic active durations and preventing client-side timer manipulation.
  4. Autonomous AI Settlement Agent: Upon job completion, an autonomous multi-turn Gemini agent evaluates an authoritative evidence packet against policy anomaly rules. The agent proposes payment capture and initiates split payouts through declared tool calls.
  5. Defense-in-Depth Policy Guards:
    • Amounts Sourced Strictly from Server: The model cannot invent numbers; capture amounts must equal engine_total_usd_cents computed by the deterministic engine.
    • Policy Rule Vetoes: 7 anomaly rules (evaluating ceilings, excessive extras, suspicious job durations, etc.) evaluate evidence before the agent acts. Any high-severity anomaly deterministically vetoes capture and locks the booking in HOLD_FOR_HUMAN.
    • Untrusted Data Quarantine: Customer symptom text and artisan notes are quarantined inside an untrusted_data JSON field with instructions forbidding prompt injection.
  6. Automated 4-Way Fair Wage Split: Final bills are split using pure integer math (paise and cents):
    • 80% directly to the artisan as a fair wage.
    • 10% to the cooperative community welfare fund.
    • 6% to the cooperative emergency capital reserve fund.
    • 4% retained for platform operations (before processing fees).
  7. Batched Multi-Receiver Payouts: Confirmed settlements trigger simultaneous PayPal Payouts transfers to distinct sandbox receiver accounts (artisan, welfare fund, reserve fund).
  8. Co-op Treasury Ledger: Every transaction, fee breakdown, and agent audit trace is published to a read-only, privacy-preserving AG Grid Community ledger.

How we built it

  • Frontend Application: Universal mobile and web client built with React Native and Expo, featuring real-time tracking maps powered by Leaflet and CartoDB Voyager tiles.
  • Backend API Server: Node.js and Express hosting the pure deterministic calculation engine, sequential event state machine, and atomic file store.
  • PayPal REST APIs:
    • Orders v2 API: Creating orders with intent: 'AUTHORIZE' and approving holds.
    • Payments v2 API: Capturing final settled amounts against active authorization holds.
    • Payouts v1 API: Disbursing batched, multi-receiver split payments.
  • Google Gemini API: gemini-3.5-flash-lite utilizing multimodal reasoning for image/text triage and function calling (capture_payment, run_payouts, hold_for_review) in the autonomous settlement loop.
  • Co-op Treasury Dashboard: Built with vendored AG Grid Community (v33), providing client-side sorting, column filtering, audit trace drawers, and CSV exports without CDN dependencies.
  • Engineering & Review: Development and comprehensive testing were assisted by Google Antigravity, with project planning and code review assisted by Claude (Anthropic).

Challenges we ran into

  • Taming LLM Non-Determinism with Money: Language models can hallucinate numbers. We instituted a strict architectural boundary: money is calculated exclusively in integer INR paise and USD cents by deterministic server code. The model proposes tools, but the server validates every parameter against the authoritative engine.
  • Gemini Model Parameter Tuning: During stress testing, we discovered that thinkingBudget: 0 triggered HTTP 400 errors on flash-lite models, while heavier models experienced latency timeouts during peak load. Running standard gemini-3.5-flash-lite without thinking configurations delivered reliable, sub-2-second triage and fast agent settlement loops.
  • Idempotency & Race Conditions: Handling asynchronous PayPal authorization redirects, worker milestones, and multi-turn agent turns required atomic in-progress flags (IN_PROGRESS) and isolated test stores to prevent double-spending or duplicate payout batches.
  • Privacy in Public Ledgers: To ensure transparent auditing without leaking sensitive information, the ledger strictly sanitizes data: receiver emails are stripped, PayPal IDs are masked to the last 4 characters, and all DOM rendering uses textContent to eliminate XSS vectors.

Accomplishments that we're proud of

  • 84 Automated Tests Passing: The entire calculation engine, policy rules, agent loops, PayPal payout splits, and ledger endpoints are verified by a comprehensive automated test suite with zero external network dependencies.
  • Mathematical Zero-Drift Guarantee: Invariant loops prove that the 4-way split and platform retention sum exactly to the captured cent across all values from $\$0.01$ to $\$1,000.00$.
  • Graceful Simulated Fallback: When credentials are omitted, the entire system gracefully falls back to a self-contained simulated mode—clearly badging simulated orders, triage, and rules-only audits.

What we learned

  • How to build robust agentic AI workflows that treat the model as an untrusted decision assistant surrounded by hard mathematical and policy guardrails.
  • How to orchestrate PayPal's Orders, Authorizations, and Payouts APIs into an automated multi-party escrow and disbursement pipeline.
  • How to integrate AG Grid Community into modern web dashboards with high performance and zero external tracking.

What's next for UniServ Pay

  • Live Forex Feeds: Transitioning from the fixed demonstration exchange rate to dynamic real-time foreign exchange feeds.
  • Cooperative Governance Portal: Enabling cooperative artisan members to review held bookings, vote on disputes, and allocate reserve funds through an on-chain or ledger-based voting interface.
  • Asynchronous Webhook Listeners: Adding PayPal webhook listeners for real-time buyer dispute notifications and automated claim resolutions.

Built With

Share this project:

Updates

Submission history