Inspiration
AI agents now shop and pay on behalf of people. That leaves merchants with a question no fraud filter was built to answer: did the human actually approve what their agent just bought? An agent can be tricked by a web page, misread its instructions, or get stuck in a loop. The card and the account are real, so the order passes normal checks. Then the human disputes a charge they never asked for, and the merchant carries the loss.
The idea came from the AWS article "Agentic Payments: The Next Evolution in the Payments Value Chain", which describes specialist agents reporting to one decision maker, and names payment authorization and fraud liability as the open problem in agent-driven shopping.
What it does
HoldFire reviews every PayPal payment before the money is taken.
- It holds first. Each order is authorized in PayPal, which reserves the money without taking it.
- Four specialist agents review it. A Mandate agent checks whether the purchase matches what the human asked their shopping agent for. Three more check amount and velocity, identity and address, and account history.
- A decision agent rules. Approve captures the payment. Decline voids it. If the evidence is mixed or the purchase is slightly outside the mandate, it holds.
- It never guesses. A held payment stays on hold until the buyer confirms or refuses it.
- It learns. Each ruling on a held payment is saved as a precedent. The next time a similar order arrives, the agents can follow that ruling without asking again.
- It keeps evidence. Every review produces a downloadable record of the mandate, the agents' reports, the decision and the PayPal IDs, ready for a dispute.
How I built it
- PayPal: direct REST calls to the sandbox. Orders v2 with intent AUTHORIZE and a test card, then the Payments v2 capture and void endpoints. The authorize-then-capture flow is what makes the review possible.
- AI: Google Gemini (gemini-3.1-flash-lite, free tier) through the google-genai SDK. Five calls per payment, each with structured JSON output and a fixed schema.
- Design: the orchestrator and the executor are plain Python. The AI gives opinions, and only code touches PayPal. Each specialist sees only the data for its own area.
- App: a Streamlit dashboard. Judges can run it locally with the steps in the README.
Challenges
- Getting a card payment to authorize directly through the Orders API in the sandbox, including the request ID header and the expiry format.
- Making a small free model hold when it should, instead of forcing an approve or decline.
- Handling Gemini's free-tier rate limits and overload errors without leaving money stuck on hold. The app retries once, then releases the PayPal hold and shows a clear message.
What I learned
How authorize, capture and void work in PayPal, how to structure a multi-agent system with a clear line between AI opinions and code that acts, and how to get reliable structured output from a small model.
What's next
- Read a signed mandate from an agent payment protocol instead of simulated data, so the instruction can't be forged.
- Message the buyer for confirmation instead of simulating it in the dashboard.
- Store precedents per buyer in a database.
- Attach the evidence record to a PayPal dispute automatically.
