Inspiration

PayPal sometimes holds a seller's money to protect buyers. For a small seller, a hold can mean days or weeks without income they already earned. When we read seller forums and PayPal's own help pages, we noticed something surprising: PayPal already publishes why payments get held (new or inactive sellers, complaints, unusual selling patterns, higher-risk items like electronics and tickets) and how to release them (add tracking and the hold is released about 24 hours after delivery; mark a service completed and it is released about 7 days later).

The information exists, but sellers who work from their phone on Instagram, WhatsApp, Facebook Marketplace or PayPal invoices often don't know it, forget it, or do it too late. Big store platforms automate some of this; small social sellers have nothing. We wanted to build the assistant they are missing.

What it does

Hold Guard follows each sale through three stages:

Before: Hold Risk Check

  • Every sale is scored against PayPal's published hold reasons, compared with the seller's own history.
  • Google Gemini reads free-text item names ("Laptop 13-inch") and recognizes higher-risk categories that simple rules miss.
  • The seller sees a plain-language warning with exactly what to do, and can get an email alert.

During: proof from a chat or a photo

  • The seller sends a photo of the shipping receipt (or types "shipped UPS 1Z…") in a phone-friendly chat.
  • Gemini reads the carrier and tracking number, Hold Guard matches it to the right sale, and the seller taps Confirm. The tracking goes to PayPal through the Orders v2 tracking API.
  • For services and digital items, one click tells PayPal the order is fulfilled.

After: when something goes wrong

  • A per-sale checklist shows which proof is done and what is missing.
  • Gemini explains in plain words why a payment may be held, and drafts a message to PayPal support.
  • When a buyer opens a dispute, Gemini drafts a reply using only real sale facts; the seller edits and approves it, and Hold Guard submits it to PayPal with a one-page Evidence Pack PDF.

Built to help honest sellers only. Hold Guard never hides anything from PayPal. It only sends true information, faster. An anti-fraud filter runs before the AI and refuses requests like "how do I split this payment so PayPal won't notice?". A scammer cannot fake a real courier's delivery confirmation, so the tool helps honest sellers and gives scammers nothing. Every action sent to PayPal needs the seller's click.

How we built it

  • Backend: Python and FastAPI, with server-rendered pages (Jinja2) that work on a phone.
  • PayPal (sandbox): Orders v2 (create, capture, add tracking), Add Tracking API (fulfillment without a tracking number), Transaction Search (seller history), Disputes API (read cases, provide evidence with a PDF), and Webhooks with signature verification.
  • AI: Google Gemini (gemini-2.5-flash) for six jobs: item reader, receipt reader, hold explainer, support message, dispute reply, and chat. The two data tasks use strict JSON output.
  • Storage: SQLite as a "proof locker" for sales, messages, disputes and chat.
  • Evidence Pack: ReportLab builds the PDF.
  • Hosting: Render, deployed from a render.yaml blueprint, with password protection for the demo.
  • Tests: 34 automated tests (risk rules, safety filter, PDF, Gemini request format, error messages, password check).

The risk score adds points for each of PayPal's published hold signals the sale shows, and caps at 100:

$$ \text{risk score} = \min\left(100,\ \text{sum of points for each signal found}\right) $$

Signal (from PayPal's hold reasons) Points
New seller (under 25 sales or $250 total) 25
No sales in the last 90 days 20
Sale is 3× the seller's average (5× or more) 25 (40)
Sudden surge in number of sales 15
Higher-risk item (electronics, tickets, travel, gift cards) 20
2 or more refunds or disputes in 90 days 20

60 or more is High, 30 to 59 is Medium, below 30 is Low.

Challenges we ran into

  • Services have no tracking number. Our first "mark completed" request included a carrier, and PayPal answered TRACKING_NUMBER_IS_MISSING. PayPal's docs showed the no-tracking-number request must send only the transaction ID and a status.
  • Disputes moving out of the seller's hands. One sandbox "item not received" case moved to PayPal's own review within minutes, and PayPal refused evidence with ACTION_NOT_ALLOWED_IN_CURRENT_DISPUTE_STATE. Hold Guard now shows each case's status in plain words, disables Submit when PayPal no longer accepts evidence, and turns every PayPal error into a plain-language message. On a fresh case we responded in time and PayPal accepted the evidence.
  • Matching disputes to sales. Some dispute records only include the buyer's transaction ID, so we added a fallback that matches by amount.
  • AI answering in sentences instead of data. The receipt and item readers need structured data, but Gemini first replied conversationally. We gave those tasks their own short "data extractor" instructions and enabled Gemini's JSON output mode.
  • The sandbox can't create real holds or deliveries. We use clearly labeled sample holds and a labeled delivery simulation; every PayPal call (orders, tracking, transaction search, disputes, webhooks) is real sandbox traffic.

Accomplishments that we're proud of

  • A complete loop on real PayPal sandbox APIs: a sale arrives, its risk is scored, the seller sends proof from a photo, and a dispute reply with a PDF reaches PayPal.
  • An AI that takes real actions, but only after the seller approves, and that refuses to help anyone get around PayPal's checks.
  • Plain-language messages throughout, so a non-technical seller always knows what happened and what to do next.

What we learned

  • How PayPal's hold, tracking and dispute systems work behind the scenes, including the dispute lifecycle and what each state allows.
  • How to make an AI reliable for data tasks (strict JSON mode, separate instructions) while keeping it conversational for explanations.
  • Practical security for a payments demo: webhook signature verification, secrets only in environment variables, password protection, and human approval before any action.

What's next for Hold Guard

  • Many sellers: let each seller connect their own PayPal account through PayPal's partner onboarding, instead of one sandbox seller per deployment.
  • Persistent storage: move from SQLite to a hosted PostgreSQL database so data survives redeploys.
  • Live delivery status from carriers, so "delivered" no longer needs a simulation.
  • Alerts where sellers already are: WhatsApp or SMS, not only email.
  • PayPal Agent Toolkit / MCP: expose Hold Guard's actions so any AI assistant can use them.

Built With

Share this project:

Updates

Submission history