LexiShield

Autonomous AI chargeback defense engine that deflects and fights PayPal disputes using telemetry, Visa CE 3.0 checks, and SHA-256 PDF evidence dossiers.

Comment

Inspiration

Online merchants lose billions each year not just to chargeback fraud, but to fragmented evidence and slow manual workflows. Crucial proof—courier GPS coordinates, outbound packing scale weights, device fingerprints, and SaaS login telemetry—lives across disconnected systems. By the time an operations team gathers screenshots manually, PayPal arbitration deadlines have passed or non-refundable $15–$30 dispute fees have already been charged.

We built LexiShield to transform chargeback management from a reactive back-office chore into an autonomous, mathematically grounded financial defense engine.

What it does

LexiShield operates as an end-to-end PayPal dispute defense and pre-chargeback deflection platform:

  1. Zero-Trust Webhook Ingress & Pre-Dispute Deflection: Verifies incoming CUSTOMER.DISPUTE.* webhooks with RSA / X.509 cryptographic checks and SSRF protection, while listening to Ethoca & Verifi RDR card-issuer alerts 20–72 hours early to issue zero-fee automated refunds before a formal dispute posts.
  2. Parallel Async Telemetry Mesh: Concurrently queries carrier logistics (GPS drop-off coordinates, signature logs, reroute flags), warehouse sensors (calibrated tare-weight variance and hardware serial scans), customer order history, and SaaS clickwrap/session telemetry using asyncio.gather.
  3. Horizontal Agentic AI & Compliance Guardrails:
    • DisputeSupervisor routes cases to domain specialists (INRAgent, SNADAgent, FraudAgent, BillingAgent) powered by a 3-tier LangChain + OpenRouter orchestration pipeline (Gemini / Llama 70B with deterministic heuristic fallback).
    • Enforces PayPal Seller Protection policy gates (such as the strict $750+ signature mandate and AVS address matching) and Visa Compelling Evidence 3.0 (CE 3.0) 120–365 day two-factor historical ledger matching.
    • Evaluates financial expected value before every action: $$E[V] = P(\text{win}) \cdot \text{OrderValue} - \bigl(1 - P(\text{win})\bigr) \cdot (\text{OrderValue} + \text{DisputeFee})$$
    • Applies a Seller Rights First defense policy while gating high-value orders (\( > \$300 \)), borderline confidence cases (\( 0.60 \le P(\text{win}) < 0.75 \)), or high-ratio merchants for Human-in-the-Loop (HITL) approval.
  4. Stage-Aware Negotiation & Cryptographic PDF Dossiers:
    • During the Inquiry stage, an autonomous conversational settlement bot negotiates directly with buyers using troubleshooting data, RMA return labels, or courtesy settlements.
    • At the Claim stage, ReportLab compiles a structured evidentiary PDF dossier stamped with a SHA-256 integrity hash (X-Dossier-SHA256), ready for PayPal arbitration and double-entry ERP ledger sync.

How we built it

  • Backend: Python 3.11+, FastAPI, Pydantic v2, and SQLAlchemy (AsyncIO + aiosqlite) for persistent dispute records, telemetry snapshots, and conversation threads.
  • AI & Policy Layer: LangChain + OpenRouter multi-tier model routing paired with deterministic compliance engines (SellerProtectionComplianceEngine and VisaCE3Engine) and ReportLab PDF synthesis.
  • Frontend Command Center: React 18, Vite, and Lucide React delivering a real-time merchant workstation with an analytics banner, HITL review queue, live buyer-vs-AI negotiation console, and one-click PDF dossier downloads.
  • Deployment & Quality: Containerized with Docker on Render, edge-hosted frontend support on Vercel, static analysis with Ruff, Mypy, and Bandit, and an automated Pytest test suite (72 passing tests).

Challenges we ran into

  • Preventing LLM hallucinations from making legally invalid claims: Pure LLM scoring could recommend fighting unwinnable disputes (e.g., tangible orders \( \ge \$750 \) missing a courier signature) or conceding winnable small-ticket claims. We solved this by anchoring AI reasoning inside deterministic PayPal §11 and Visa CE 3.0 compliance guardrails and a Seller Rights First supervisor gate.
  • Keeping Ephemeral Container Storage Reliable: On cloud deployments with ephemeral container disks, cached PDF dossiers or local SQLite state can reset between restarts. We built async database synchronization paired with on-demand deterministic PDF dossier recompilation so merchants can always download verified SHA-256 dossiers.
  • Stage-Appropriate Tone: An aggressive legal rebuttal hurts retention during early buyer misunderstandings. We introduced dynamic persona switching between a helpful Customer Diplomat (Inquiry stage) and an Adversarial Legal Defense voice (Claim stage).

Accomplishments that we're proud of

  • Built a complete multi-agent architecture spanning four specialized dispute domains (INR, SNAD, Fraud, Billing) plus pre-chargeback alert deflection and double-entry ERP ledger events.
  • Implemented genuine Visa CE 3.0 lookback verification and cryptographic SHA-256 ReportLab PDF dossiers generated in seconds.
  • Achieved 72 passing automated tests alongside clean ruff, mypy, and bandit security checks.

What we learned

  • Combining deterministic financial math (\(E[V]\)), hard payment-network policy rules, and multi-tier LLM fallback produces far more trustworthy automation than prompting an LLM alone.
  • Real-time merchant trust depends on transparency: surfacing exact win probabilities, compliance citations, HITL overrides, and downloadable cryptographic PDFs makes autonomous AI auditable.

What's next for LexiShield

  • Direct production OAuth & Webhook onboarding for Shopify and WooCommerce merchants.
  • Live FedEx / UPS / DHL carrier tracking webhooks and automated NetSuite / QuickBooks / Xero journal entry connectors.
  • Expanded card-network rule packs (Mastercard Mastercom compelling evidence templates and multi-currency FX fee optimization).

Built With

Share this project:

Updates

Submission history