Payguardian

website 1.2
website 1.1
API Calls on paypal sandbox 1
Paypal sandbox invoice for churn recovery 1.1
Paypal sandbox invoice for churn recovery 1.2

Inspiration

Subscription businesses silently bleed up to 9% of their recurring revenue to expired cards and lose thousands more to avoidable chargeback fees. PayGuardian is an autonomous financial copilot built natively on PayPal and Gemini that turns those payment failures into instant recoveries. The moment a recurring charge declines, PayGuardian calculates a tailored loyalty discount and dispatches a one-click PayPal recovery invoice. And when a customer opens a dispute, it steps in during PayPal’s early inquiry window to negotiate an automated settlement offer—resolving friction in seconds before it ever escalates into a costly chargeback.

What it does

PayGuardian acts as an autonomous, always-on revenue protection agent for PayPal merchants, targeting the two largest sources of silent payment leakage:

Involuntary Churn Recovery (Failed Billing): When an automated recurring subscription charge fails (BILLING.SUBSCRIPTION.PAYMENT.FAILED), PayGuardian evaluates the subscriber's tenure and lifetime value. Instead of sending passive dunning emails that go ignored, it dynamically computes a personalized retention discount (between 10% and 25%) and issues a hosted, one-click payable invoice directly via the PayPal Invoicing v2 API.
Pre-Chargeback Dispute Arbitration: When a buyer opens a claim (CUSTOMER.DISPUTE.CREATED), PayGuardian intercepts the ticket during PayPal's critical INQUIRY lifecycle stage—before it escalates into a formal bank chargeback. The agent assesses escalation risk, calculates an optimal partial refund settlement (30% to 50%), and dispatches a formal resolution offer via the PayPal Customer Disputes v1 API, saving merchants from non-refundable dispute fees ($15–$25 per claim) and protecting merchant account standing.
Real-Time Telemetry & Audit Cockpit: Provides a split-screen operations dashboard that streams live webhook executions, displays the AI agent's step-by-step financial rationale, and surfaces direct links to generated PayPal Sandbox checkout invoices.

The net financial protection per intercepted incident is modeled by:

$$\text{Net Protected Value} = (R_{\text{recovered}} \times (1 - d)) + \sum (F_{\text{chargeback}} - S_{\text{offer}})$$

where R_recovered is the base subscription value, 'd' is the dynamic retention discount, F_chargeback is the avoided dispute penalty fee, and S_offer is the proactive inquiry-stage settlement.

How we built it

We engineered PayGuardian from the ground up with a clean, 100% PayPal-native architecture designed for asynchronous reliability:

Backend & Webhook Orchestration: Built with Python and FastAPI, utilizing non-blocking BackgroundTasks to ingest live PayPal Sandbox webhooks (/api/paypal/webhook) and process payment telemetry without dropping events.
PayPal Sandbox Integration: Implemented a dedicated PayPalClient managing OAuth2 Bearer token exchanges (/v1/oauth2/token), the three-step Invoicing v2 workflow (draft creation, dispatch, and payer_view_url metadata extraction), and Customer Disputes v1 settlement arbitration (/v1/customer/disputes/{id}/make-offer).
Agentic Reasoning Engine: Powered by the Google GenAI SDK (gemini-2.0-flash / gemini-3.8-flash) using structured JSON output enforcement so every retention discount and settlement percentage adheres strictly to merchant margin guardrails.
Live Operations Cockpit: Built a lightweight, zero-build-step frontend in HTML5, CSS3, and Vanilla JavaScript with 3-second polling against /api/events and interactive simulation triggers for instant end-to-end testing.

Challenges we ran into

LLM Latency & Availability Spikes: During testing, high-demand 503 UNAVAILABLE spikes and multi-model retry loops caused the frontend dashboard to hang while waiting for AI responses. We solved this by implementing fast-fail execution timeouts paired with a deterministic heuristic policy engine—ensuring PayGuardian dispatches recovery invoices and dispute offers in under 2 seconds even if external model endpoints experience congestion.
PayPal Invoicing Link Extraction: Newly created draft invoices in PayPal Sandbox do not immediately expose the customer-facing checkout URL until the invoice transitions to SENT status. We structured a sequential pipeline that creates the draft, triggers /send, and immediately queries the invoice metadata to extract the exact payer_view_url.
Local Webhook Tunneling: Testing live asynchronous PayPal Sandbox events required exposing our local FastAPI server securely via ngrok and mapping PayPal's webhook payload structures cleanly to our background workers.

Accomplishments that we're proud of

End-to-End Autonomous Execution: Moving beyond passive AI alerts—PayGuardian executes real financial state changes on PayPal Sandbox, generating actual payable invoices and submitting live dispute settlement offers without human intervention.
Sub-2-Second Response Resilience: By combining structured Gemini reasoning with deterministic fallback guardrails, the platform never blocks or drops a time-sensitive payment event.
Zero-Clutter Merchant UX: Designing a single-screen command center where a merchant or judge can simulate a failed renewal or dispute, inspect the AI's exact financial reasoning, and click straight into the live PayPal Sandbox invoice in seconds.

What we learned

The Value of PayPal's INQUIRY Stage: Intercepting buyer friction before it escalates into a formal claim is the highest-leverage point in payment operations, turning a binary win/lose chargeback battle into a collaborative micro-settlement.
Guardrails Matter in Financial AI: Giving an LLM direct access to issue discounts and refunds requires strict mathematical clamping (e.g., capping retention discounts at $25\%$ and settlements at $50\%$) alongside structured JSON schemas.

What's next for PayGuardian

Webhook Cryptographic Signature Verification: Implementing PayPal's PAYPAL-TRANSMISSION-SIG header verification for production-grade webhook security.
Multi-Tier Customer LTV Scoring: Connecting merchant CRM and historical order volume data so the agent can dynamically adjust retention incentives for VIP vs. new subscribers.
Automated Evidence Submission: Expanding our Disputes v1 integration to automatically compile shipping tracking and usage logs via /provide-evidence when a claim cannot be settled during the inquiry phase.