{"id":50978301,"url":"https://github.com/visa/vic-reference-agent","last_synced_at":"2026-06-19T11:03:49.626Z","repository":{"id":363451726,"uuid":"1140231049","full_name":"visa/vic-reference-agent","owner":"visa","description":"Open source reference app to run and experience agentic commerce functionality. ","archived":false,"fork":false,"pushed_at":"2026-06-18T20:37:33.000Z","size":493,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T22:23:40.981Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/visa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-23T02:00:42.000Z","updated_at":"2026-06-18T20:37:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/visa/vic-reference-agent","commit_stats":null,"previous_names":["visa/vic-reference-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/visa/vic-reference-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visa%2Fvic-reference-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visa%2Fvic-reference-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visa%2Fvic-reference-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visa%2Fvic-reference-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/visa","download_url":"https://codeload.github.com/visa/vic-reference-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visa%2Fvic-reference-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34528144,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-19T11:03:48.926Z","updated_at":"2026-06-19T11:03:49.613Z","avatar_url":"https://github.com/visa.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Visa Intelligent Commerce Reference Agent\n\n\u003e Reference implementation for Visa Intelligent Commerce with AI-powered shopping agent\n\n[![Python](https://img.shields.io/badge/Python-3.12.8-3776AB.svg?style=flat\u0026logo=python\u0026logoColor=white)](https://www.python.org)\n[![Node](https://img.shields.io/badge/Node-22-339933.svg?style=flat\u0026logo=node.js\u0026logoColor=white)](https://nodejs.org)\n[![React](https://img.shields.io/badge/React-19.0.0-61DAFB.svg?style=flat\u0026logo=react\u0026logoColor=white)](https://reactjs.org)\n[![Vite](https://img.shields.io/badge/Vite-6.0.7-646CFF.svg?style=flat\u0026logo=vite\u0026logoColor=white)](https://vitejs.dev)\n[![FastAPI](https://img.shields.io/badge/FastAPI-latest-009688.svg?style=flat\u0026logo=fastapi\u0026logoColor=white)](https://fastapi.tiangolo.com)\n\n## Overview\n\nThis repository contains a full-fledged reference application demonstrating end-to-end Visa Intelligent Commerce (VIC) capabilities with an AI-powered shopping agent. The application showcases complete integrations with:\n\n- 🛒 **Visa Intelligent Commerce (VIC)** - End-to-end agentic commerce flow with AI-driven product discovery and checkout\n- 🎫 **Visa Token Service (VTS)** - Payment token provisioning and management for secure transactions\n- 🔐 **Visa Payment Passkey (VPP)** - WebAuthn passkey authentication for frictionless, secure checkout\n- 🤖 **AI Shopping Agent** - Conversational product search and personalized recommendations using LangGraph\n- 🔌 **Model Context Protocol (MCP)** - Tool-based AI interactions for seamless shopping experiences\n\n### Network Support\n\n**Note:** VIC (Visa Intelligent Commerce) is Visa card network centric. This reference implementation is designed specifically for the Visa card network and does not support other payment card networks.\n\n## Architecture\n\nThe application consists of 5 microservices:\n\n```\n┌────────────────────────────────┐\n│  Reference Agent Frontend      │\n│  (React - HTTPS Port 3000)     │\n│  - Shopping Agent UI           │\n│  - Card Management UI          │\n│  - VPP Integration via VTS     │\n└────────────────┬───────────────┘\n                 │\n                 ▼\n┌────────────────────────────────┐\n│  Reference Agent Backend       │\n│  (FastAPI - Port 8000)         │\n│  - Shopping Agent              │\n│  - Card/Token Management       │\n│  - VTS/VIC Integration         │\n└────────────────┬───────────────┘\n                 │\n                 ▼\n┌────────────────────────────────┐ ┌──────────────────────────────┐\n│  Reference Merchant MCP        │ │  Reference Merchant Frontend │\n│  (Express - Port 8002)         │ │  (React - Port 3001)         │\n│  - MCP Tool Server             │ │  - Product Browsing          │\n│  - AI Shopping Tools           │ │  - Cart Management           │\n│  - Form Elicitation            │ │  - Checkout Flow             │\n└────────────────┬───────────────┘ └──────────────┬───────────────┘\n                 │                                │\n                 ▼                                ▼\n                 ┌────────────────────────────────┐\n                 │  Reference Merchant Backend    │\n                 │  (FastAPI - Port 8001)         │\n                 │  - Product API                 │\n                 │  - Cart API                    │\n                 │  - Order API                   │\n                 └────────────────────────────────┘\n```\n\n## Prerequisites\n\nBefore you begin, ensure you have:\n\n### Required Software\n- **Docker** and **Docker Compose** (recommended for running the application)\n- **mkcert** (for generating HTTPS certificates)\n- **Node.js** 22+ (only required for local development without Docker)\n- **Python** 3.12.8+ (only required for local development without Docker)\n\n### Required Credentials\n\nContact your Visa representative to obtain:\n- Visa Token Service (VTS) credentials\n- Visa Intelligent Commerce (VIC) credentials\n- Token Requestor (TR) credentials\n- Message Level Encryption (MLE) keys\n- Visa Payment Passkey (VPP) credentials\n\nYou will also need:\n- LLM API credentials (OpenAI or Anthropic) for the AI agent\n\n**Important:** Developers must obtain their own LLM provider credentials separately. The LLM API credentials (OpenAI or Anthropic) are not Visa API credentials and must be acquired directly from the respective LLM providers.\n\n## Quick Start\n\nThe easiest way to run the entire application is with Docker Compose.\n\n### 1. Generate SSL Certificate\n\nIn order for the passkey integration to work properly, the frontend must use HTTPS, which means that a trusted SSL certificate is needed for localhost.\n\n**Install mkcert:**\n- **macOS**: `brew install mkcert`\n- **Windows**: `choco install mkcert`\n- See [mkcert repository](https://github.com/FiloSottile/mkcert) for other installation methods\n\n**Add the root CA (one-time operation):**\n```bash\nmkcert -install\n```\n\n**Generate certificates:**\n```bash\ncd reference-agent-frontend\nmkcert localhost 127.0.0.1 ::1\ncd ..\n```\n\n### 2. Configure Environment Variables\n\nSet up the shared API keys used by Docker Compose (project root):\n\n```bash\ncp .env.sample .env\n# Edit .env and set MERCHANT_API_KEY, AGENT_API_KEY, and MCP_API_KEY\n# Generate strong values, e.g.: openssl rand -hex 32\n```\n\nSet up the reference-agent-backend environment:\n\n```bash\ncd reference-agent-backend\ncp .env.sample .env\n# Edit .env and fill in all credentials\ncd ..\n```\n\nSet up the reference-agent-frontend environment:\n\n```bash\ncd reference-agent-frontend\ncp .env.sample .env\n# Edit .env and fill in all credentials\ncd ..\n```\n\n### 3. Start All Services\n\nFrom the project root:\n\n```bash\ndocker-compose up --build\n```\n\nThis will start all 5 services:\n- **reference-agent-frontend**: https://localhost:3000\n- **reference-agent-backend**: http://localhost:8000\n- **reference-merchant-frontend**: http://localhost:3001\n- **reference-merchant-backend**: http://localhost:8001\n- **reference-merchant-mcp**: http://localhost:8002\n\n### 4. Use the Application\n\nSee [USER_GUIDE.md](USER_GUIDE.md) for a step-by-step walkthrough of adding cards, setting up passkeys, and shopping with the AI agent.\n\n### 5. Stop All Services\n\n```bash\ndocker-compose down\n```\n\n## Project Structure\n\n```\nvic-reference-agent/\n├── reference-agent-backend/      # FastAPI backend with AI agent\n├── reference-agent-frontend/     # React frontend for AI shopping\n├── reference-merchant-backend/   # FastAPI backend for merchant\n├── reference-merchant-frontend/  # React frontend for merchant\n├── reference-merchant-mcp/       # MCP server for shopping tools\n├── docker-compose.yml            # Docker Compose configuration\n└── README.md                     # This file\n```\n\nEach subdirectory has its own README with detailed setup instructions for local development.\n\n## Running Without Docker Compose\n\nIf you prefer not to use Docker Compose, you can run each service individually. Each subdirectory contains its own README with setup and run instructions:\n\n- [reference-agent-backend/README.md](reference-agent-backend/README.md)\n- [reference-agent-frontend/README.md](reference-agent-frontend/README.md)\n- [reference-merchant-backend/README.md](reference-merchant-backend/README.md)\n- [reference-merchant-frontend/README.md](reference-merchant-frontend/README.md)\n- [reference-merchant-mcp/README.md](reference-merchant-mcp/README.md)\n\n### Service Dependencies\n\nWhen running services individually, start them in this order:\n\n1. **reference-merchant-backend** (port 8001)\n2. **reference-merchant-mcp** (port 8002) - depends on merchant backend\n3. **reference-agent-backend** (port 8000) - depends on merchant MCP\n4. **reference-merchant-frontend** (port 3001) - depends on merchant backend\n5. **reference-agent-frontend** (port 3000) - depends on agent backend\n\n## Troubleshooting\n\nHaving issues? See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common problems and solutions.\n\n## Support\n\nFor issues and questions, please open an issue in the repository.\n\nFor Visa API credentials and support, contact your Visa representative.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvisa%2Fvic-reference-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvisa%2Fvic-reference-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvisa%2Fvic-reference-agent/lists"}