Inspiration

The idea began with a frustrating real-world experience: ordering a laptop online, returning a defective unit, and then spending days stuck in limbo—not knowing whether the delay was caused by pickup scheduling, warehouse inspection, merchant approval, the payment gateway, or the issuing bank.

Every traditional e-commerce portal shows a single opaque status like "Refund Processing", even though a refund actually crosses multiple independent parties: customer, merchant, reverse-logistics carrier, payment gateway (PayPal), issuing card bank, and regional consumer regulations. We asked a simple question:

Why should customers struggle to get their own money back after a valid return?

We set out to build a platform that separates physical return tracking from financial refund tracking, identifies exactly where and why a refund is stalled, keeps customers and merchants informed with honest evidence, and uses agentic AI safely without ever allowing an LLM to move money on its own.


What it does

Shipkart & Agentic Refund Intelligence & Resolution Platform unites two decoupled, production-deployed web platforms across 9 live cloud microservices:

  1. Shipkart Marketplace (ecommerce_platform — System of Record)

    • Customer Storefront & Merchant Seller Hub: Full multi-merchant e-commerce flow supporting INR catalog pricing paired with explicit USD Merchant-Direct PayPal Sandbox checkout and isolated AES-256-GCM merchant credential custody.
    • Inventory & Financial Ledger Guarantees: 15-minute SELECT FOR UPDATE stock reservations, ReportLab PDF tax invoices, 6-step signed PayPal webhook verification, and append-only PaymentLedgerEvent records.
  2. Agentic Refund Intelligence Platform (refund_intelligence_platform)

    • Separated Dual-Track Lifecycle: Explicitly separates Physical Return milestones (RETURN_REQUESTED → PICKUP_SCHEDULED → IN_TRANSIT → DELIVERED_TO_MERCHANT → INSPECTION_COMPLETED) from Financial Settlement milestones (INVESTIGATING → NEEDS_EVIDENCE → PENDING_MERCHANT_APPROVAL → PAYPAL_COMPLETED → CONFIRMED_POSTED).
    • LangGraph 3-Agent Orchestrator: Coordinates intake_node → investigation_node → resolution_node (powered by NVIDIA NIM nvidia/nemotron-3.5-super-vl-120b-a12b with deterministic offline fallback) to verify uploaded evidence hashes, query telemetry, synthesize plain-English briefs for both buyer and merchant, and recommend next steps.
    • Deterministic SLA Delay & ETA Engines: Zero-LLM Python engines evaluate DELAY-001 through DELAY-006 bottleneck ownership (CARRIER, MERCHANT, PAYPAL, ISSUER_OR_BANK) and compute honest stage-remaining ETA bands—returning NOT_ESTIMABLE whenever required milestones are missing rather than fabricating optimistic delivery dates.
    • Mandatory Human-in-the-Loop Financial Boundary (REF-001): AI agents are strictly advisory (execute_paypal_refund = false). Only an authenticated merchant in Seller Hub recording an immutable RefundApproval row (with rationale) can trigger a PayPal capture refund.
    • Operations Command Center & Three Simulators: Dedicated ops supervision portal (ops_frontend) plus three standalone FastAPI mock services (carrier_simulator, issuer_simulator, regulatory_simulator) modeling card ARN traces (DELAY-006) and versioned IN/US compliance rules (RBI/FEMA, CPA, CFPB Reg E, FTC).

How we built it

1. Cross-Platform Security & Bridge Architecture

Instead of embedding LLM logic inside the e-commerce database, the two platforms communicate exclusively over cryptographic boundaries:

  • Inbound Event Sync: ecommerce_platform signs every return event with HMAC-SHA256 (X-Bridge-Signature) before pushing to POST /api/v1/bridge/shipkart/return-event.
  • Service Read & Advisory Write: agent_backend authenticates back to Shipkart using short-lived HS256 Service JWTs (iss = refund-intelligence-platform) to fetch live PayPal capture status and post fenced advisory briefs.
  • Prompt Injection Defense: Customer free-text inputs are wrapped inside strict <<<UNTRUSTED_CUSTOMER_TEXT>>> fences during intake_node, while evidence uploads undergo magic-byte inspection, 10 MB size limits, and SHA-256 deduplication.

2. Deterministic Math & Policy Engines

To guarantee financial correctness, settlement checks, SLA attributions, and ETA bounds are computed deterministically outside the LLM:

  • INR Catalog to USD PayPal Settlement & Conservation (REF-002): Because PayPal does not support domestic INR-to-INR transactions between Indian test accounts, Shipkart displays INR prices and settles explicit USD totals using fixed-precision Decimal arithmetic:

A_USD = round_2(A_INR / R_FX), 0 < r_k ≤ C_capture − ∑_{i < k} r_i

where r_k is the k-th refund request against capture balance C_capture.

  • Stage-Remaining ETA Horizon (ETAService): Given the verified current physical and financial stage s, the estimated credit window aggregates the remaining deterministic stage intervals R(s):

[ETA_min, ETA_max] = t_now + ∑_{j ∈ R(s)} [τ_{j,min}, τ_{j,max}]

  • Deterministic SLA Delay Classification (DELAY-001..DELAY-006): Each transition duration Δt_d is tested against rule threshold SLA_d ∈ {24h, 48h, 72h}:

Breach_d = I(Δt_d > SLA_d) ⇒ Owner_d ∈ {CARRIER, MERCHANT, PAYPAL, ISSUER_OR_BANK}

  • Human Financial Gate (REF-001) & Idempotency (REF-003): Payout execution is gated by a hard Python/DB invariant requiring both an immutable approval record and an explicit merchant trigger:

AllowPayout = I(RefundApproval = APPROVED) ∧ I(execute_paypal_refund_agent = False) ∧ unique(idempotency_key)

3. Tech Stack & Cloud Deployment

  • Backend & Agents: Python 3.12, FastAPI, SQLAlchemy 2.0, Alembic, psycopg v3, LangGraph, langchain-nvidia-ai-endpoints (NVIDIA NIM), Celery, Cryptography (AES-256-GCM), ReportLab, Pillow.
  • Frontends: React 18, TypeScript, Vite 5, Tailwind CSS, PayPal JS SDK, Nginx.
  • Cloud Infrastructure: Dual Render Blueprints (render.yaml) running 9 Dockerized services in Oregon sharing a managed PostgreSQL instance via strict schema isolation (public vs. refund_intelligence).

Challenges we ran into

  1. Cross-Currency PayPal Sandbox Constraints: PayPal does not allow domestic INR-to-INR flows across Indian Sandbox accounts. Designing clean multi-merchant INR order totals alongside USD PayPal Sandbox captures and partial/full refund validation without float rounding drift required strict Decimal allocation models and dual-currency tracking in the Ops UI.
  2. Render Free Tier Single-Database Limit & Schema Isolation: Render Free Tier limits each account to one free PostgreSQL database. Rather than merging two platform schemas or losing Alembic isolation, we implemented configurable PostgreSQL DB_SCHEMA=refund_intelligence, SQLAlchemy SET search_path connection listeners, and schema-scoped Alembic version_table_schema so both platforms coexist safely on a single shipkart-db instance.
  3. Synchronous vs. Asynchronous Bridge Timeouts on Cold Starts: On free-tier cloud workers without a dedicated Redis daemon (CELERY_TASK_ALWAYS_EAGER=true), synchronous webhook handling initially risked timeouts while running the 3-agent LLM graph inline. We fixed Celery eager mode to use memory:// (eliminating Redis retry hangs), offloaded the agent pipeline into FastAPI BackgroundTasks, and added bidirectional push/pull recovery endpoints (Sync from Shipkart).
  4. Honest Separation of PayPal Completion vs. Bank Credit: Many payment demos wrongly mark a refund as "money in your bank" the instant PayPal returns COMPLETED. Modeling DELAY-006 taught us to distinguish gateway instruction settlement from issuing-bank posting latency—keeping simulated bank/carrier/regulatory subsystems transparently labeled (SIMULATED) at every UI layer.

Accomplishments that we're proud of

  • True End-to-End Live Cloud System: All 3 web portals (shipkart-customer-26, shipkart-merchant-26, refund-ops-26), both FastAPI backends, 3 simulator microservices, and PostgreSQL run live together on Render with real PayPal Sandbox capture and refund settlement.
  • Database-Enforced Immutability & 9 Hard Guardrails: PostgreSQL BEFORE UPDATE/DELETE triggers lock refund_approvals and audit_logs, paired with deterministic Python policy checks (REF-001–REF-004, AUTH-001/002, CASE-001, QTY-001, DATA-001).
  • Explainable Multi-Agent UX Embedded Everywhere: Customers, merchants, and operations leads all see transparent agent reasoning, evidence validation status, dual physical/financial timelines, and plain-English ETA disclosures in real time.

What we learned

  • LLMs belong in reasoning and triage—never in financial state transitions: Pairing LangGraph/NVIDIA NIM with deterministic Python policy, ETA, and delay engines yields the flexibility of AI investigation with the predictability of traditional fintech ledgers.
  • Boundary contracts beat monoliths: Connecting Shipkart and the Refund Intelligence Platform via HMAC-SHA256 webhooks and HS256 Service JWTs made both systems independently testable, deployable, and auditable.
  • Transparency builds user trust more than fake precision: Explicitly telling a customer "PayPal refund completed; issuing bank card posting is still unconfirmed (2–6 days)" or returning NOT_ESTIMABLE when carrier scans are missing eliminates the exact ambiguity that causes refund support tickets.

What's next for Shipkart & Agentic Refund Intelligence & Resolution Platform

  • Production Carrier & Bank Acquisition Integrations: Replace the carrier_simulator and issuer_simulator adapters with real carrier webhook feeds (tracking pickup/RTO scans) and card-network ARN settlement polling.
  • Proactive Omnichannel Notifications: Add real-time email, SMS, and push notifications whenever a DELAY-001..006 threshold is breached or an ARN posts to the customer's card.
  • Automated Chargeback Pre-Emption & Dispute Packets: Assemble signed evidence bundles (delivery photos, SHA-256 checksums, PayPal capture/refund IDs, and immutable audit trails) automatically into PayPal Dispute API representations.
  • Multi-Currency FX Ledger & Persistent Object Storage: Integrate external S3/R2 storage for long-lived evidence retention beyond ephemeral container disks and add live FX rate locking across international refund corridors.

Built With

Share this project:

Updates

Submission history