DisputeIQ

Dashboard Overview: Highlights the key metrics and active queue state.
Webhook & Dispute Details: Zooms in on the exact details of PP-SANDBOX-999 and the webhook status.
AI Triage & Recommendation: Expands the Gemini AI analysis view, showing the confidence score and automated reasoning.
Automated Defense Response: Displays the fully drafted, policy-compliant response ready for merchant action.

Inspiration

Online merchants lose billions of dollars annually to chargeback fraud and operational fatigue. When a customer files a dispute (like an Item Not Received claim), merchants are flooded with unstructured event data, tight resolution deadlines, and complex policy requirements. Manually triaging each case leads to missed deadlines, lost evidence, and unnecessary revenue loss. We built DisputeIQ to bridge real-time payment gateway webhooks with advanced generative AI—turning a stressful administrative burden into an automated, data-driven defense system.

What it does

DisputeIQ is an automated chargeback resolution portal designed for online merchants:

Webhook Ingestion: Captures incoming PayPal dispute webhooks (CUSTOMER.DISPUTE.CREATED) in real time.
AI Triage Engine: Uses Gemini AI to analyze raw dispute payloads, evaluate claim reasons, and generate a confidence score alongside actionable recommendations (ACCEPT, REJECT, or REVIEW).
Response Generation: Drafts professional, policy-compliant merchant defense responses ready for submission to payment processors.
Merchant Dashboard: Provides a clear Streamlit interface tracking active disputes, automation rates, protected revenue, and historical resolutions.

How we built it

DisputeIQ is built on a modular architecture:

Backend: Powered by FastAPI to handle incoming webhook requests asynchronously, run business logic, and manage SQLite database transactions.
Database: SQLite (disputes.db) for lightweight, persistent storage of incoming webhooks, raw JSON payloads, and resolution histories.
AI Integration: Integrated with the Google GenAI SDK (gemini-3.8-flash) to parse dispute parameters, analyze shipping evidence gaps, and output structured JSON recommendations.
Frontend: Built with Streamlit, featuring custom CSS styling, dynamic status metrics, and expander components to inspect AI reasoning and raw PayPal data.
Deployment & Testing: Cloud deployment on Render, validated end-to-end using PowerShell testing suites simulating live PayPal sandbox events.

Challenges we ran into

Environment Synchronization: Resolving database desynchronization between local development environments and live cloud deployments on Render required careful URL routing and dynamic database loading.
Network & Socket Stability: Mitigating intermittent SSL handshake drops during external API calls required building exponential backoff retry loops and robust fallback mechanisms so the merchant dashboard remains resilient.
Data Deserialization: Normalizing varying nested structures inside raw PayPal webhook payloads (strings vs. pre-parsed JSON dicts) to ensure smooth rendering on the Streamlit frontend.

Accomplishments that we're proud of

End-to-End Validation: Successfully building and validating a live pipeline where a simulated PayPal webhook triggers Gemini AI analysis and instantly updates the merchant dashboard in seconds.
Graceful Degradation: Designing a backend that gracefully handles network interruptions without losing dispute state or breaking the user experience.
Clean UI/UX: Crafting a clear dashboard that transforms raw financial metadata into actionable business metrics and ready-to-use dispute defense drafts.

What we learned

Asynchronous Resilience: Gained deep experience in fault-tolerant API design, specifically how to build retry layers and fallback paths around generative AI calls within payment pipelines.
Seamless Webhook Architecture: Standardized methods for testing and decoupling webhook receivers from frontend visualization dashboards.

What's next for DisputeIQ

Automated Evidence Assembly: Integrating directly with carrier APIs (FedEx, UPS, DHL) to automatically pull proof of delivery and tracking manifests based on order IDs.
Direct PayPal Resolution API: Adding one-click dispute defense submission directly back into PayPal's Disputes API to eliminate manual copy-pasting.
Multi-Gateway Support: Expanding webhook handlers to support Stripe, Square, and Shopify chargebacks under a unified AI triage command center.

Built With

ai/ml
chargeback-management
e-commerce
fastapi
fintech
gemini-ai
genai
generative-ai
google
json
paypal
powershell
python
render
requests
rest-api
sqlite
streamlit
uvicorn
webhooks

Submitted to

PayPal AI Hackathon

Created by

Rizqah Olajide Adedokun
I designed and engineered the backend architecture using FastAPI (main.py), creating asynchronous API routes to handle real-time PayPal webhooks, manage state transitions, and connect with our SQLite database (database.py).

I built the PayPal Developer Platform integration (paypal_client.py), authenticating via OAuth2 and setting up event handlers to parse raw CUSTOMER.DISPUTE.CREATED payloads into actionable transaction metadata.

I integrated Google Gemini AI (gemini-flash-latest) (ai_agent.py), crafting structured prompt templates that evaluate dispute payload parameters, score chargeback risk, suggest resolution pathways (REFUND, FIGHT, PARTIAL REFUND), and generate formatted defense response letters.

I developed the merchant UI using Streamlit (app.py), designing interactive metrics cards, filterable dispute tables, and AI reasoning modules for one-click dispute management.

I managed cloud deployment and documentation, setting up production pipelines on Render (backend) and Streamlit Community Cloud (frontend), configuring environment variable security, and writing the technical documentation and API specifications (README.md).

Raola-max Adedokun

Updates

Raola-max Adedokun started this project — Nov 08, 2026 12:18 PM EST

Leave feedback in the comments!