PayFlow Agent

An AI agent that shops and negotiates like a buyer, then pays on PayPal — supervised by a governance dashboard with approval gates, payouts and receipts.

Comment

Inspiration

Autonomous agents are getting remarkably good at acting — browsing, negotiating, transacting. The missing half is governance: nobody can watch why an agent spent money, stop it before it does, or audit what happened afterwards. With payments in the loop, that risk multiplies. We asked: what if an AI agent had real PayPal superpowers, but was born inside a control room?

PayFlow Agent is our answer — the agent does the work; the platform provides the discipline.

What it does

  • Autonomous checkout agent — a buyer agent browses a curated catalog through the official PayPal MCP server, haggles with an independent seller agent, and executes real sandbox PayPal orders. Live validation: the Titan USB-C hub negotiated from $59.99 → $45.
  • Human-in-the-loop spending gate — any order ≥ $500 is held in pending_approval until an admin approves or rejects it from the dashboard.
  • A governance dashboard, not a chat toy — every tool call (args, results, duration) streams into an expandable trace timeline; an AG Grid audit feed tracks all money movement with receipts; smart PayPal buttons capture the order in-context.
  • Freelancer payout pipeline — manager submits the deliverable → an LLM quality gate scores it (live run: approved at 0.93 confidence) → admin releases a Payout batch. In regions where PayPal doesn't serve payout senders (like India), batches are clearly labeled simulated — the real REST path ships behind one env var.
  • Webhooks → AI-written receipts — approval/capture events are matched against our own transaction store, flip the status to paid, and an LLM writes the receipt from verified facts only: "Thank you for purchasing the Titan 11-in-1 USB-C Hub for $45.00. Your PayPal order 42D08450M5493690L is now paid." Unknown event ids get an honest 202 ignored — incoming envelopes are never trusted blindly.

How we built it

A TypeScript monorepo: Express + TS backend, Next.js dashboard. The backend spawns the official @paypal/mcp npm package as a child process over stdio, auto-minting and refreshing sandbox OAuth tokens. One tool-calling loop (max 10 rounds) merges four in-process domain tools — get_product_catalog, negotiate_with_seller, create_paypal_order, execute_paypal_payout — with filtered MCP tools, recording every step. Orders run on @paypal/paypal-server-sdk; payouts use the documented /v1/payments/payouts endpoint; guarded amounts flow through a single shared runPayout() service. The brain goes through an OpenAI-compatible gateway (Groq in this build — one env var swaps providers). Zod-validated env, pino-style logs, a full Postman collection, and a Render blueprint ship in-repo.

Challenges we ran into

  • Token budgets: Groq's free 8k tokens/min cap choked on full MCP schemas → we added a PAYPAL_MCP_TOOLS filter, keeping the agent sharp on what matters.
  • Reasoning models misbehave: openai/gpt-oss-120b hides its thinking in a reasoning field — replaying it broke tool loops, and tiny max_tokens starved it before it wrote anything. We fixed both (strip on replay; max_completion_tokens: 500 for receipts) and one nudge for empty replies.
  • India payout restriction: PayPal blocks Payouts from India-based senders. Rather than fake success, we built explicit PAYOUTS_MODE=mock — simulated batches are always labeled, with the real code path ready to switch on.

Accomplishments we're proud of

A fully validated end-to-end pipeline: chat → negotiation → sandbox order → webhook → AI receipt, plus a gig payout approved and paid out in the same session. And a strict honesty table in our docs separating what's real from what's simulated — we'd rather score points for transparency than lose them for pretending.

What we learned

  • MCP is the fastest path to real platform superpowers for agents.
  • Guardrails are design features, not afterthoughts: matching-first webhooks, bounded tools, approval gates, and labeled simulation are what make agent autonomy trustworthy.
  • Reasoning models need different plumbing than chat models — and earn it.

What's next

Postgres-backed stores (our records are already swap-compatible), payout retry queues + a refund console, signature-verified webhooks on a public Render URL, and a real (sandbox) Payouts demo from a supported sender country.

Built With

  • ag-grid
  • ai-agents
  • express.js
  • groq
  • human-in-the-loop
  • llm
  • model-context-protocol
  • multi-agent-systems
  • next.js
  • node.js
  • oauth
  • paypal-mcp
  • paypal-orders-api
  • paypal-payouts-api
  • paypal-sandbox
  • react
  • tailwindcss
  • tool-calling
  • typescript
  • webhooks
Share this project:

Updates

Submission history