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:
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-GCMmerchant credential custody. - Inventory & Financial Ledger Guarantees: 15-minute
SELECT FOR UPDATEstock reservations, ReportLab PDF tax invoices, 6-step signed PayPal webhook verification, and append-onlyPaymentLedgerEventrecords.
- 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
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 NIMnvidia/nemotron-3.5-super-vl-120b-a12bwith 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-001throughDELAY-006bottleneck ownership (CARRIER,MERCHANT,PAYPAL,ISSUER_OR_BANK) and compute honest stage-remaining ETA bands—returningNOT_ESTIMABLEwhenever 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 immutableRefundApprovalrow (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 versionedIN/UScompliance rules (RBI/FEMA,CPA,CFPB Reg E,FTC).
- Separated Dual-Track Lifecycle: Explicitly separates Physical Return milestones (
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_platformsigns every return event withHMAC-SHA256(X-Bridge-Signature) before pushing toPOST /api/v1/bridge/shipkart/return-event. - Service Read & Advisory Write:
agent_backendauthenticates back to Shipkart using short-livedHS256Service 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 duringintake_node, while evidence uploads undergo magic-byte inspection,10 MBsize limits, andSHA-256deduplication.
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 domesticINR-to-INRtransactions between Indian test accounts, Shipkart displaysINRprices and settles explicitUSDtotals using fixed-precisionDecimalarithmetic:
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 stages, the estimated credit window aggregates the remaining deterministic stage intervalsR(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_dis tested against rule thresholdSLA_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,
psycopgv3, 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 (publicvs.refund_intelligence).
Challenges we ran into
- Cross-Currency PayPal Sandbox Constraints: PayPal does not allow domestic
INR-to-INRflows across Indian Sandbox accounts. Designing clean multi-merchant INR order totals alongside USD PayPal Sandbox captures and partial/full refund validation withoutfloatrounding drift required strictDecimalallocation models and dual-currency tracking in the Ops UI. - 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, SQLAlchemySET search_pathconnection listeners, and schema-scoped Alembicversion_table_schemaso both platforms coexist safely on a singleshipkart-dbinstance. - 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 usememory://(eliminating Redis retry hangs), offloaded the agent pipeline into FastAPIBackgroundTasks, and added bidirectional push/pull recovery endpoints (Sync from Shipkart). - 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. ModelingDELAY-006taught 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/DELETEtriggers lockrefund_approvalsandaudit_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-SHA256webhooks andHS256Service 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_ESTIMABLEwhen 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_simulatorandissuer_simulatoradapters 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..006threshold 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
- alembic
- celery
- docker
- fastapi
- javascript
- jwt
- langchain
- langgraph
- minio
- nginx
- nvidia
- paypal
- postgresql
- pydantic
- pytest
- python
- react
- redis
- render
- sqlalchemy
- tailwindcss
- typescript
- uvicorn
- vite