-
-
-
customer's order summary
-
payment status
-
payment using paypal
-
Risk Monitor (manager login)
-
manager's dashboard
-
Policy Engine (manager login)
-
customer's support tickets
-
customer's refunds
-
AI operations (manager login)
-
customer ai support
-
manager's ticket tab
-
ag studio (manager dashboard)
-
customer's orders
-
customer shopping
-
manager's approval tab
-
manager's approval tab
-
customer dashboard
-
Login Page
Inspiration
Every online store has the same 2 a.m. problem: a customer writes "where is my order?" or "I want a refund", and nobody is awake to answer. AI chatbots can answer, but most of them either can't touch real data or, worse, say "your refund has been processed" when nothing happened. In payments, an AI that hallucinates a refund is not a UX bug, it is a financial and trust incident.
We wanted an AI support team that is genuinely useful (it looks up the real order, payment and shipment, and can actually move money through PayPal) while being impossible to talk into a refund it shouldn't give. Our design rule became the product's tagline:
The AI proposes. The policy engine decides. PayPal confirms.
What it does
SupportFlow AI is an autonomous customer-support and financial-operations platform for online businesses.
For customers
- Shop and pay with PayPal Checkout (Sandbox): order created, buyer approves on PayPal, payment captured, order marked Paid only when PayPal returns the capture.
- Chat with an AI support team that answers from the customer's real orders, payments and shipments, cites the store's knowledge base, and can request refunds or cancellations.
- Every financial outcome appears as a live action card whose status comes from the execution engine, never from the AI's wording: Refund completed by PayPal, Waiting for approval, Escalated, or Failed (and why).
For managers
- Approval center: each pending refund shows a risk summary, the full policy trace (every condition, expected vs actual, which rule matched and its version), and a live re-check against PayPal before approval.
- Policy editor with immutable versions and a dry run on any order.
- AI operations trace: every agent step and tool call, with what was allowed or refused. No hidden chain-of-thought is stored or shown.
- Manager copilot (read-only tools) and AG Studio analytics dashboards (Financial, Support, AI Ops, Risk) that the AI can extend in plain English.
- PayPal API log, refunds with reconcile and retry, audit log, risk monitor, multi-tenant isolation.
Three refund requests, three outcomes (USD demo thresholds)
| Request | Policy outcome | What happens |
|---|---|---|
| Under \$50, captured, within the refund window, low risk | Auto-execute | Execution engine re-validates, calls PayPal Refund, shows the PayPal refund id |
| \$50 to \$250 | Requires approval | Waits for a manager; approval re-checks the capture, then calls PayPal |
| Over \$250, high risk, or repeated refund requests | Escalate | Ticket escalated; the card states that no refund was issued |
How we built it
- Frontend: React + TypeScript + Vite + Tailwind; AG Studio for the analytics workspace (lazy-loaded).
- Backend: FastAPI, SQLAlchemy, Alembic, PostgreSQL 16 with pgvector, Redis rate limiting, JWT auth with 4 roles and tenant isolation on every query.
- PayPal: every REST call goes through the APIMatic-generated PayPal Server SDK for Python: Orders v2 (create, get, capture) and Payments v2 (refund capture, get capture, get refund). Webhooks are verified with PayPal's
verify-webhook-signatureAPI before they touch any record. We used the APIMatic PayPal context-plugin skills to look up the exact SDK contract (keyword-only params, error unions, retry and timeout semantics) instead of guessing, and wrote it down inpaypal-plan.md. - AI: six LangGraph agents (Orchestrator, Order investigation, Policy intelligence, Risk assessment, Resolution, Manager copilot) plus the AG Studio dashboard agent, powered by Google Gemini (with an automatic fallback model) or OpenAI. Each agent has its own tool allow-list; refused tool calls are recorded. RAG over uploaded PDF/DOCX/Markdown policies with Gemini embeddings in pgvector, with citations.
- Deterministic policy engine: ordered rules over a fact catalog, 11 operators, 5 outcomes, immutable versions, and a stored evaluation trace for every decision.
- Execution engine (the only code that can call PayPal's refund): a state machine with a UNIQUE idempotency key, row locks, revalidation immediately before the PayPal call, and the same key sent as
PayPal-Request-Id. For any refund on a capture of amount $c$, the engine enforces
$$\sum_i r_i \le c$$
at the moment of execution, not at the moment the AI asked.
- Unknown outcomes are never guessed: a timeout or a truncated response moves the action to
OUTCOME_UNKNOWN, and a reconciler re-reads it from PayPal using the same request id, so a retry can never create a second refund. - Quality: 66 backend tests against a real PostgreSQL database (only PayPal's HTTP transport is stubbed, so the real SDK builds and parses every request) and 14 frontend tests; ruff, mypy and
tscclean. One-command Docker Compose stack.
Challenges we ran into
- INR in the PayPal Sandbox. Our first live checkout failed with a 422 because our Sandbox merchant could not receive INR. Instead of hiding it, we surfaced PayPal's issue code with a currency hint in the UI, made the seed refuse to run with mismatched currency data, and added a one-switch
DEMO_CURRENCY=USDmode that also rescales the policy thresholds. - The PayPal return URL. After approving on PayPal, the buyer landed on a dead port because the dev server URL (5173) leaked into the Docker setup (8080). We now derive the return and CORS URLs from the actual frontend port.
- Making the SDK's edge cases safe. A 4xx body without
debug_idfails to decode in the SDK; on a refund that ambiguity must not be read as "failed". We classify every transport and decode failure as never sent vs outcome unknown and test each path. - Gemini in the real world. We hit a 404 (
*-latestmodel aliases exist only on thev1betaAPI) and504 DEADLINE_EXCEEDEDfrom Google. We pinned the API version, added a timed per-model Test AI connection diagnostic, a retry, and automatic fallback to a second model. - AI honesty in the UI. Early on, when every Gemini call failed, the chat still fell back to rules but was labelled as answered by Gemini. We now track every LLM call and label the turn rules (LLM failed). If an embedding call fails, retrieval falls back to a labelled local index instead of crashing the chat.
Accomplishments that we're proud of
- Zero fake success. No mock response is ever shown as a real transaction. Sample data is labelled everywhere and is refused by the execution engine. With no PayPal keys, every PayPal action fails visibly with "not configured".
- A refund cannot happen twice: UNIQUE idempotency key, row lock and
PayPal-Request-Id, proven by tests that replay the same request. - Explainable decisions. Any refund can be traced from the customer's sentence, to the agent's tool calls, to the exact policy rule and version, to PayPal's response.
- Works without any AI key in a clearly labelled deterministic mode, so the financial logic never depends on the model.
What we learned
- In payments, the hard part is not the happy path, it is the unknown path: timeouts, retries and webhooks arriving before or after the API response.
- LLMs are excellent at understanding the customer and wording the answer, and should have exactly zero authority over money.
- Generated SDKs plus a written contract sheet beat guessing from memory: typed error unions and explicit retry semantics changed how we designed failure handling.
What's next for SupportFlow AI
- PayPal Disputes API so chargebacks feed the same policy and approval pipeline.
- Partial refunds and exchanges proposed by the AI, with policy limits per product category.
- Email and SMS notifications, staff MFA, HTTP-only cookie sessions.
- A self-serve policy template library for different store types.
Built With
- ag-grid
- alembic
- apimatic
- docker
- fastapi
- google-gemini
- langchain
- langgraph
- nginx
- openai
- paypal
- paypal-orders-api
- paypal-payments-api
- paypal-webhooks
- pgvector
- postgresql
- pydantic
- python
- react
- redis
- render
- sqlalchemy
- tailwindcss
- typescript
- vite