guardrail-pay

Family Guardian stops scam and accidental payments. PayPal holds payments until an AI risk check and, if needed, a guardian approves them. The AI can only tighten rules, and every decision is logged.

Comment

Guardrail: Family payment safety on PayPal rails

Inspiration

Two things cost families money every day. Seniors get tricked by scam calls ("Grandma, it's me, I'm in jail, send bail money and don't tell Mom"), and kids tap "buy" on a game at midnight. In both cases the money is gone before anyone in the family hears about it. Banks warn the person under pressure, and that person is the least able to stop and think. We wanted to add the missing pause between "tap pay" and "money leaves", and bring the family in during that pause.

What it does

Every payment goes through Guardrail. It starts as a PayPal order with intent AUTHORIZE: the money is held but not charged. Shield, our AI, checks the recipient, the amount compared with the person's usual spending, the time of day and the payment note for signs of a scam or an impulse purchase.

  • Safe payments are captured straight away. A $5 school lunch goes through with no friction.
  • Risky payments stay on hold. The guardian gets an email alert and a card on their dashboard with Shield's reasons, and taps Approve or Cancel.
  • Cancelled payments are voided through PayPal, so nothing is ever charged. If something turns out to be a scam after it was sent, the guardian can refund it.
  • Unanswered holds are voided automatically after 24 hours. Silence means no.

Grandma sees a large, calm warning: "Wait. This payment may be a scam." The reasons are in plain words, and she has three choices: call her family, cancel, or send anyway (which still asks the family first). The guardian taps "Call Grandma first: what to ask", and Shield writes the questions to ask her, such as "Did you talk to Sam yourself, on the number you always use?" It never suggests calling the scammer back.

The core safety rule: the AI can only make a payment stricter, never looser. The family's rules live in code, in one function, apply_guardrails: a spending cap, new recipients need approval, a 30-minute cooling-off period for new payees, and a Pause all payments switch. The final verdict is always whichever is stricter, Shield's or the rules'. If Gemini fails or returns invalid output, the payment is held, never sent. The AI never sees PayPal credentials, and every Shield verdict, rule decision and guardian action goes into an audit log shown on the dashboard.

Both screens install as phone apps (PWAs), and the demo starts with a spoken scam call on Grandma's phone.

How we built it

  • Backend: Python, FastAPI and Pydantic, with an in-memory store (no database for the hackathon)
  • Frontend: static HTML, Tailwind CSS and vanilla JavaScript, installable as two PWAs ("Family Pay" for the senior, "Guardian" for the parent). Designed first in Google Stitch.
  • PayPal (Sandbox): OAuth 2.0, Orders API v2 with intent AUTHORIZE, then Payments API capture, void and refund. Tested end to end against the real Sandbox.
  • AI: Google Gemini 2.5 Flash through the google-genai SDK, using structured JSON output validated by Pydantic, with one retry and then a hold if it still fails. Gemini also writes the plain-language warnings and the guardian's call script.
  • Alerts: a Zapier webhook that emails the guardian when a payment is held
  • Demo: a simulated incoming call on Grandma's phone, spoken with the browser's built-in text-to-speech
  • Hosting: Render

Each payment moves through clear states: created → approved by the payer on PayPal → authorized (held) → scored by Shield → checked by the rules → then either captured automatically, or held for the guardian until it's captured, voided, or voided automatically when the hold expires.

Challenges we ran into

  • PayPal from India. Our first sandbox test accounts were Indian, and checkout failed with "This seller doesn't accept payments in your currency." We rebuilt the setup with US sandbox Business and Personal accounts and a new app linked to them.
  • The free Gemini tier. It allows about 5 requests per minute and sometimes returns "high demand" errors. Shield has to fail safe, so an outage holds the payment instead of letting it through. For a reliable live demo, we save Gemini's real answers and replay them when the same payment comes in.
  • Reliable structured output. Every model response must match a strict Pydantic schema, or it's retried once and then treated as a failure, which means a hold.
  • Holds can't wait forever. A PayPal authorization doesn't stay valid indefinitely, so we added an automatic void after 24 hours with no answer.
  • A warning seniors will actually read. Short sentences, large text, no jargon, and the senior stays in control. "Send anyway" still goes to the family, so she's never simply blocked.
  • Voices on Android. Android reports voice languages as en_US instead of en-US, so our scam call played silently on Android until we fixed the voice lookup.

Accomplishments that we're proud of

  • A real PayPal Sandbox payment: approved by the payer, held, then sent by the guardian and refunded. In a separate test, a payment was cancelled and the hold was voided.
  • The stricter-only rule is enforced in code. The AI can't approve anything the family's rules hold, and a failed AI check means a hold.
  • A full audit trail of every AI verdict, rule decision and guardian action, shown as a timeline on the dashboard.
  • A working Pause all payments switch: while it's on, even a safe $5 lunch payment is held for the guardian.
  • The guardian's call script: the AI helps the family have the right conversation, not just make a yes/no decision.
  • Two installable phone apps and a demo that opens with a spoken scam call.

What we learned

  • AI is safest as a brake, not an accelerator. Letting the model only tighten decisions, and treating its failures as "hold", made it possible to use AI with real money.
  • PayPal's authorize-then-capture flow is what makes this idea possible. The hold is real, so "wait for the family" costs the user nothing.
  • Safety design is about who gets the warning. Warning the person under pressure isn't enough. Bringing in someone calm, with the right questions to ask, is what stops the scam.

What's next for guardrail-pay

  • PayPal webhooks, plus push and SMS alerts for guardians
  • A database, accounts and multiple guardians, with rules for who must approve
  • A child's view of the app, plus separate rules for kids and seniors
  • Learning each person's normal spending pattern, so unusual payments stand out more
  • Native iOS and Android apps, building on the installable apps we have now
  • A production review of PayPal's policies for family and minor accounts

Built with

python · fastapi · pydantic · uvicorn · paypal-orders-api · paypal-payments-api · paypal-sandbox · google-gemini · google-genai · tailwindcss · javascript · html · pwa · web-speech-api · zapier · render · google-stitch

Built With

Share this project:

Updates

Submission history