statuspal

An AI agent that explains why your PayPal payment is pending, held, or declined, tells you what to do next, and says honestly when the data can’t tell.

Comment

Inspiration

People see a payment marked "pending," "on hold," or "declined" with no real explanation. They don't know whether to wait, act, or worry, so they end up in support queues. We wanted to turn that confusing moment into a clear one, without an AI that confidently makes things up.

What it does

Status Pal reads a payment's data and explains, in plain language, what the status means, the most likely causes, and what to do next.

Every point is labeled either Confirmed by data (literally present in the transaction fields) or Common cause, not confirmed (general knowledge). When the data doesn't explain a status, such as an on-hold payment with no reason, Status Pal says "I can't tell from this data" and points the user to where they can find out, instead of guessing.

The app has two tabs:

  • Live PayPal Sandbox: creates a real test order through the PayPal Sandbox API (fake money), reads it back, shows the exact data the AI receives, and explains it.
  • Example statuses: typed-in examples (pending, on hold, declined, refunded). These are not fetched from PayPal.

How we built it

  • PayPal: PayPal Sandbox REST API called directly from Python. We authenticate with OAuth, create an order, and retrieve it by ID.
  • AI: Google Gemini, with a system prompt that limits the model to what the data supports and requires the confidence labels. The app tries a fast model first, falls back to a second model if the first is busy, and streams answers so users see text quickly.
  • Frontend: Streamlit, with an expandable box that shows the raw PayPal data the AI sees.
  • Safety: API keys stay in a local .env file that is never committed, and we use only Sandbox test data.

Challenges we ran into

  • Honest labeling. Early versions marked general knowledge as "confirmed," so we tightened the prompt until only fields literally present in the data can be marked confirmed.
  • Busy AI servers. Free-tier AI services sometimes return "high demand" errors, so we added retries, a fallback model, and streaming.
  • Sandbox limits. The PayPal Sandbox mostly produces orders in the CREATED state, so held and declined cases are shown through the examples tab.
  • Keeping secrets safe. GitHub's secret scanning blocked a push that contained a key, and we fixed it before anything went public.

Accomplishments that we're proud of

  • An assistant that is honest about uncertainty and shows its evidence.
  • A working end-to-end flow from a real PayPal Sandbox order to a plain-language explanation.
  • Built from scratch by a beginner in a few days.

What we learned

For payment experiences, trust comes from clarity and honesty more than from sounding confident. Showing users what the data does and doesn't say matters most.

What's next for Status Pal

  • Support more statuses, including real held, declined, and dispute data as the Sandbox allows
  • Shipment tracking and dispute context in explanations
  • Proactive alerts when a held payment changes state
  • A merchant-side version to reduce support tickets

Built With

Share this project:

Updates

Submission history