Inspiration
Small merchants face fraud, false disputes, unpaid invoices and quiet customer churn, usually alone. The tools they get are opaque: a payment gets blocked and nobody explains why. We wanted something different: a protective shield that holds risky payments but explains itself in plain language, plus a virtual CFO that helps the business grow. The merchant always has the last word.
What it does
Shield protects every payment with deterministic rules. Gemini never makes the decision; it only explains it.
approved: normal payments are captured automatically. held: for example 6+ micro-payments followed by a large amount. The PayPal authorization stays open and nothing is captured until the merchant clicks Unlock and validate, which triggers a real capture. alerted: PayPal declines, or a dispute claims “not received” while tracking says delivered. There is nothing to capture, so the merchant simply acknowledges. blocked: an automated burst of test payments. The authorization is voided.
Ally is a virtual CFO, fully decoupled from Shield. It analyzes the last 30 transactions to spot churning loyal customers, upsell trends, cash-flow dry spells and unpaid invoices. It is throttled and de-duplicated, and customers are pseudonymized before Gemini sees anything.
The Command Center dashboard shows KPIs, live Shield and Ally feeds, AG Grid tables with a Source column (PayPal Sandbox, verified webhook, or simulated), and live health indicators for PayPal and Gemini.
How we built it
A FastAPI backend runs Shield and Ally in parallel with asyncio.gather.
PayPal Sandbox: Orders v2 (intent=AUTHORIZE), authorization, Payments v2 capture and void, OAuth2, and webhooks with signature verification. A buyer approving an order triggers a webhook, Sentinel authorizes it, Shield decides, then it captures, holds or voids. We also used the PayPal-Mock-Response header for negative testing (INSTRUMENT_DECLINED, DUPLICATE_INVOICE_ID). Google Gemini: rewrites each Shield decision as a short, reassuring message, and writes Ally’s suggestions from deterministic analytics. Deterministic fallbacks keep everything working if a call fails. AG Grid: the verdict and suggestion tables. Render: hosts the live demo, with admin actions protected by a token.
A test suite covers the rules, the PayPal flows (against a fake PayPal server), webhook de-duplication and the security checks.
Challenges we ran into
One payment, many webhooks. A single payment fires order, authorization and capture events, plus retries. We had to de-duplicate them so it is counted once. Webhook-driven decisions. The webhook authorizes the order before the buyer returns to the app, so risk context and test options had to be stored when the order is created. PayPal doesn’t provide every risk signal. Micro-payment bursts and tracking data are not in its API. We simulate them and label every row by source, so nothing is passed off as real. Privacy. We stripped e-mail addresses and names from what goes to Gemini and restore the name locally for display. Keeping humans in control. A declined payment must never show an Unlock button, because there is nothing to capture.
Accomplishments that we're proud of
A real PayPal Sandbox payment that Shield holds, then the merchant unlocks, producing a real capture that shows up as completed in the Business account. A strict separation: rules decide, AI explains, humans validate. Honest, auditable data: every verdict says whether it came from the real Sandbox, a verified webhook or a simulation. A deployed, protected demo with deterministic fallbacks.
What we learned
PayPal’s authorize-then-capture model is a natural “hold” primitive for fraud protection. Webhook-driven flows need idempotency from day one. Keeping the AI out of the decision loop makes the system easier to test, audit and trust. And being upfront about what is simulated makes a demo more credible, not less.
What's next for Paypal sentinel
Real Invoicing API integration so Ally can send polite payment reminders. Real risk signals (tracking data, velocity computed from transaction history) instead of simulated ones. Persistent storage, merchant accounts and multi-merchant support, with per-merchant rule tuning. A move from Sandbox to PayPal Live, with proper onboarding.
