PayFlow Intelligence

Inspiration

Small and medium-sized merchants rarely go out of business because they are unprofitable—they fail because of acute working-capital timing gaps. A wholesale coffee roaster might have thousands of dollars in sales on paper, yet still miss a critical Friday supplier cutoff because their cash is trapped across two places:

Frozen PayPal Dispute Holds: Buyers filing Item Not Received or Not As Described claims that lock up hundreds of dollars for 30+ days unless the merchant manually cross-references courier proof-of-delivery PDFs or negotiates partial settlements.
Overdue B2B Invoices: Unpaid customer receivables sitting in PayPal Invoicing with no prioritization by historical payment reliability or settlement speed.

We built PayFlow Intelligence to act as an autonomous treasury and dispute-resolution agent that bridges the gap between trapped receivables and urgent supplier obligations—turning frozen PayPal disputes and overdue invoices into immediate Friday working capital.

What it does

When a merchant states an urgent treasury goal—such as "I need $1,800 by Friday to pay our wholesale coffee supplier, Apex Roasters"—PayFlow Intelligence orchestrates an end-to-end working-capital recovery plan:

Read-Only Cash Gap Diagnosis: Queries the live PayPal Reporting API (GET /v1/reporting/balances) to compute the exact working-capital shortfall: $$\text{Initial Gap} = \max(0, \text{Target Obligation} - \text{Available Balance})$$
Parallel Multi-Domain Triage: Fans out concurrently across two PayPal domains:
- Dispute Hold Recovery: Inspects open PayPal Resolution Center cases (GET /v1/customer/disputes), matches them against local courier proof-of-delivery records (dhl_pod_CAP88210.pdf), and uses GPT-4.1 mini to choose between contesting with evidence (PROVIDE_EVIDENCE), making a game-theoretic partial refund offer (MAKE_PARTIAL_OFFER) to immediately unlock 80% of held cash on subjective quality claims, or accepting unfulfilled claims (ACCEPT_FULL_CLAIM).
- Overdue Invoice Scoring: Pulls unpaid B2B invoices (GET /v2/invoicing/invoices), filters for Friday settlement eligibility based on customer historical reliability ($\ge 0.90$) and days overdue ($\le 7$), and drafts tailored payment reminders.
Interactive AG Grid Command Center & Human-in-the-Loop Gate: Halts at an explicit LangGraph interrupt() checkpoint before mutating any external state. The merchant reviews ranked liquidity levers in AG Grid, toggles checkboxes to see real-time solvency projections, and clicks Approve & Execute.
Gated Execution & Closed-Loop Self-Verification: Resumes from the saved checkpoint via Command(resume=...) to execute approved PayPal write operations—attaching shipment tracking (POST /v1/shipping/trackers-batch), submitting dispute evidence (provide-evidence), sending partial settlement offers (make-offer), dispatching B2B invoice reminders (POST /v2/invoicing/invoices/{id}/remind), and triggering the outbound supplier settlement (POST /v1/payments/payouts). Finally, a verification node performs read-back GET calls to confirm state transitions in an immutable audit log.

How I built it

We designed PayFlow Intelligence around a Neuro-Symbolic Financial Architecture where the LLM never hallucinates a single dollar figure:

Agent Orchestration (LangGraph): Built a stateful StateGraph (diagnose_cash_gap $\rightarrow$ parallel analyze_disputes & analyze_invoices $\rightarrow$ synthesize_plan $\rightarrow$ merchant_approval interrupt $\rightarrow$ execute_plan $\rightarrow$ verify_and_audit) backed by MemorySaver with JsonPlusSerializer for Pydantic state persistence.
Structured AI Reasoning (Azure OpenAI GPT-4.1 mini): Used LangChain's .with_structured_output() with strict Pydantic schemas (DisputeDecisionSchema and InvoiceReminderSchema) so GPT-4.1 mini performs cross-document evidence matching, strategic settlement selection, and legal/commercial note drafting.
Deterministic Treasury Math (Pure Python): All financial calculations happen in deterministic Python. Each lever's risk-adjusted expected recovery is calculated as: $$E[\text{Recovery}i] = \text{Net Unlockable USD}_i \times P(\text{Recovery}_i)$$ To prioritize cash velocity, levers are ranked using a time-discounted priority score: $$\text{Priority Score}_i = \frac{E[\text{Recovery}_i]}{\log_2(\text{Est. Settlement Hours}_i + 2)}$$ Outbound supplier payouts only trigger if the hard solvency constraint is satisfied: $$\text{Available Balance} + \sum{i \in \text{Approved}} \text{Friday Cash}_i \ge \text{Supplier Obligation}$$
**PayPal Sandbox Integration (httpx + `paypal-agent-toolkit