Inspiration

Chargebacks, first-party friendly fraud, and merchandise non-receipt claims inflict over $100 billion in merchant losses annually. When a cardholder repudiates a purchase or disputes a delivery, merchants face severe structural operational challenges:

  1. Strict Response Deadlines: Merchants face rigid 10-to-20 day windows to compile multi-factor evidentiary dossiers or suffer automatic claim forfeiture.
  2. Card Scheme Rule Bifurcation: Non-receipt claims (Visa Reason Code 13.1 / PayPal MERCHANDISE_OR_SERVICE_NOT_RECEIVED) demand strict Proof of Fulfillment (carrier dispatch timestamps, GPS coordinates, license delivery logs). Conversely, Card-Absent Fraud claims (Visa Reason Code 10.4) require Visa Compelling Evidence 3.0 (CE3.0) rules—matching historical, undisputed transactions across IP addresses, device fingerprints, and delivery coordinates over 120–365 days. Conflating these evidentiary frameworks leads to instant issuer rejection.
  3. The LLM Hallucination Risk: Generative AI without deterministic guardrails risks fabricating tracking numbers, inventing license keys, or citing synthetic demo fixtures as verified evidence, permanently compromising merchant credibility with payment processors.

We built DisputeSentinel AI to give PayPal merchants an enterprise-grade defense platform that connects directly to the PayPal Disputes API (/v1/customer/disputes), automates Visa CE3.0 correlation, and enforces six deterministic validation gates that cryptographically guarantee evidence integrity before any response touches payment rails.


What It Does

DisputeSentinel AI operates as an autonomous copilot and defense engine for merchants on the PayPal Developer Platform:

  • Live PayPal Disputes Synchronization: Ingests disputes via PayPal REST API v1 (/v1/customer/disputes) and processes inbound webhooks (CUSTOMER.DISPUTE.CREATED, CUSTOMER.DISPUTE.UPDATED) with fail-closed HMAC/RSA signature verification and idempotency controls.
  • Dual Transaction ID Resolution: Intelligently maps dispute references to both PayPal Seller Transaction IDs (6EH...) and Buyer Transaction IDs (33M...), preventing multi-party account confusion.
  • Evidentiary Provenance Tracking: Assigns immutable audit labels (VERIFIED_EXTERNAL, VERIFIED_MERCHANT, MERCHANT_ATTESTED, MANUAL_ENTRY, SYNTHETIC_DEMO) to every evidence item. Self-proclaimed claims fail safely to MERCHANT_ATTESTED and require explicit human review.
  • Visa Compelling Evidence 3.0 (CE3.0) Engine: Automatically crawls prior settled merchant telemetry to correlate qualifying historical transactions matching IP address, device fingerprint, and physical shipping address within 120–365 days with zero prior fraud disputes, formally establishing CE3.0 compliance to shift liability back to the card issuer.
  • AI-Powered Defense Brief Synthesis: Leverages Google Gemini 1.5 Pro (with Groq LLaMA 3.3 and deterministic rule-based fallback) to generate professional, legally formatted defense briefs tailored specifically to the dispute reason code.
  • Six Deterministic Validation Gates: Every synthesized dossier must pass 6 non-negotiable gates:
    1. Gate 1 (Provenance & Existence): Asserts all cited transactions exist in local telemetry; strictly blocks SYNTHETIC_DEMO fixtures from live submission.
    2. Gate 2 (Carrier Syntax): Validates courier tracking numbers via regex (UPS 1Z..., FedEx 12-15 digits, USPS, DHL).
    3. Gate 3 (Financial Precision): Verifies rebuttal amount matches the disputed total to the exact cent.
    4. Gate 4 (Prompt Injection & Legal Claims): Neutralizes jailbreaks and blocks illegal CE3.0 liability shift assertions on INR disputes.
    5. Gate 5 (Human-in-the-Loop Threshold): Forces manual merchant review if evidence completeness is under 85% or reliance on manual attestation is high.
    6. Gate 6 (Approval & HATEOAS Parity): Enforces a server-side cryptographic SHA-256 merchant approval hash match and verifies PayPal's HATEOAS provide_evidence action link is active.
  • Safe Submission Architecture: Enforces dry_run=true previews and a strict ENABLE_LIVE_PAYPAL_SUBMISSION=false sandbox safety lock to guarantee zero accidental live mutations.

How We Built It

DisputeSentinel is engineered with clean-room dependency isolation and zero external vendor lock-in:

  • Backend Architecture: Built with Python 3.13 and FastAPI on an async ASGI architecture with SQLAlchemy 2.0 and SQLite / aiosqlite for high-speed local processing.
  • PayPal Integration: Native integration with PayPal REST Disputes API v1 (/v1/customer/disputes), including OAuth2 client-credential token cycling, webhook verification (verify-webhook-signature), HATEOAS action parsing, and structured payload construction.
  • AI & Synthesis: Built on Google Gemini 1.5 Pro via Google GenAI SDK, with fallback support for Groq LLaMA 3.3 and a hermetic, zero-network deterministic rule synthesizer.
  • Frontend Experience: Modern React 19 with TypeScript, Tailwind CSS, and AG Grid Community (Quartz Dark Theme) for dense, responsive financial operations. Features real-time state isolation across disputes and live CE3.0 qualification badges.
  • Security & Integrity: Cryptographic SHA-256 payload digests for human approval signatures, HMAC-SHA256 Bearer tokens for session security, and clean separation between live PayPal Sandbox credentials and synthetic offline test fixtures.
  • Verification: Hermetic test suite with 59 passing tests covering every gate, router, and schema, plus end-to-end browser walkthroughs automated with Playwright.

Challenges We Ran Into

  1. Card Scheme Workflow Bifurcation: Ensuring the system rigorously separated the legal burdens for Visa Reason 13.1 (INR) and Visa Reason 10.4 (CE3.0 Fraud). We solved this by implementing Gate 4, which actively sanitizes and blocks unauthorized CE3.0 liability shift claims if attached to an INR dispute.
  2. Preventing AI Hallucinations in High-Stakes Finance: Generative models naturally want to please the user by completing fields, which in chargebacks can mean fabricating tracking codes or delivery timestamps. We built 6 hard deterministic gates in Python that sit downstream of the LLM; if the LLM invents a single piece of data, the gates reject the dossier before it ever reaches the approval ledger.
  3. Synthetic Demonstration vs. Live Sandbox Isolation: Demonstrating CE3.0 correlation requires complex historical multi-transaction data that sandbox accounts rarely possess. We engineered a dual-path pipeline: synthetic fixtures (TX-DEMO-FRAUD-001, TX-DEMO-HIST-001/002) allow end-to-end demonstration, while Gate 1 and Gate 5 permanently isolate and forbid synthetic fixtures from ever being submitted to PayPal's live API.

Accomplishments That We're Proud Of

  • 100% Hermetic Test Coverage: All 59 backend tests pass without requiring external network calls or unmocked credentials.
  • End-to-End Cryptographic Chain: From the moment a dispute is synced to the moment the merchant approves it, every mutation is stamped with SHA-256 hashes and provenance labels.
  • Complete, Coherent Product: We didn't build a slide deck or a simple wrapper script; DisputeSentinel is a full-stack, enterprise-grade application with a high-density AG Grid cockpit, automated CE3.0 correlation, and multi-gate safety locks.

What We Learned

  • The Nuance of Visa CE3.0 Rules: Qualifying for an issuer liability shift requires precise historical transaction pairing (two prior undisputed transactions within 120–365 days sharing matching data elements). Automating this unlocks massive revenue recovery for digital merchants.
  • Deterministic AI Architecture: In financial and legal workflows, AI should be used for synthesis and drafting, while deterministic, hardcoded validation gates must hold the absolute veto power over submissions.

What's Next for DisputeSentinel AI

  • E-Commerce Platform Connectors: Direct Shopify, WooCommerce, and BigCommerce plugins to pull real-time order logs, carrier webhooks, and IP telemetry automatically.
  • Mastercard Collaboration Support: Expanding beyond Visa CE3.0 to support Mastercard's First-Party Trust and Compelling Evidence equivalent frameworks.
  • Automated Settlement & Negotiation: Using PayPal's /adjudicate and /accept-claim endpoints to offer partial refunds or automated settlement offers when evidentiary completeness falls below cost-effective defense thresholds.

Instructions for Judges (Run Locally)

DisputeSentinel is 100% open-source and runnable locally in minutes:

1. Prerequisites

  • Python 3.11+ (Python 3.13 recommended)
  • Node.js 18+ and npm
  • Git

2. Clone and Setup Backend

git clone https://github.com/Zenfox-690/DisputeSentinel.git
cd DisputeSentinel

# Create and activate virtual environment
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On Linux/macOS:
source .venv/bin/activate

# Install backend dependencies
cd backend
pip install -r requirements.txt

# Run backend test suite (all 59 tests pass hermetically)
pytest tests/ -v

# Start FastAPI backend (Port 8000)
python run.py

3. Setup and Start Frontend

# In a new terminal window:
cd DisputeSentinel/frontend
npm install
npm run build
npm run preview -- --port 3000

4. Experience the Demo

Open http://localhost:3000 in your browser:

  1. Review the Dispute Sentinel Cockpit displaying synced PayPal disputes.
  2. Select DEMO-CE30-FRAUD to observe the Visa CE3.0 Engine matching qualifying historical transactions (TX-DEMO-HIST-001, TX-DEMO-HIST-002).
  3. Click Synthesize Defense Brief to trigger AI synthesis with deterministic Gate 1–6 validation.
  4. Review the generated canonical hash and click Approve & Submit (Dry-Run) to inspect the verified PayPal payload.

Built With

Share this project:

Updates

Submission history