# Research: Razorpay MCP Server & Agentic Payments

**Date:** 2026-04-03
**Status:** Research complete
**Context:** Deep dive into Razorpay's MCP server, agentic payments, and what's usable for Annie (personal AI agent making payments on behalf of Rajesh)

---

## Executive Summary

Razorpay has the most comprehensive MCP server in the Indian payments ecosystem: **45+ tools**, official Go implementation, remote hosted option at `https://mcp.razorpay.com/mcp`, and active development. However, it is **100% merchant-facing** -- requires Razorpay merchant API keys, and all payment flows assume the Razorpay account holder is *receiving* payments, not *making* them.

The **one exception** is RazorpayX Payouts (business banking), which enables *sending* money -- but requires a RazorpayX business account with KYC.

For Annie's use case (personal agent paying merchants), the viable paths are:
1. **Payment Links / QR codes as "self-pay"** (register as sole proprietor, 2% cost)
2. **Agentic Payments via UPI Reserve Pay** (NPCI pilot, closed user group, not available yet)
3. **MCP for merchant-side automation** (if Rajesh ever needs to accept payments)

---

## 1. Official Razorpay MCP Server

### Repository
- **URL:** https://github.com/razorpay/razorpay-mcp-server
- **Language:** Go
- **License:** MIT
- **Stars:** 216
- **Created:** 2025-04-26
- **Latest release:** v1.2.1 (2025-09-26)
- **Docker Hub:** `razorpay/mcp`

### Remote vs Local

| Aspect | Remote (Recommended) | Local |
|--------|---------------------|-------|
| URL | `https://mcp.razorpay.com/mcp` | Docker container on your infra |
| Setup | Zero -- just API keys | Docker + Go required |
| Auth | Base64(key:secret) in Authorization header | Env vars RAZORPAY_KEY_ID + RAZORPAY_KEY_SECRET |
| Updates | Automatic | Manual (pull new Docker image) |
| Uptime | 99.9% SLA | Self-managed |
| Tool restrictions | Some write tools disabled (refunds, close QR, instant settlement, registration links) | All tools available |
| Protocol | MCP over Streamable HTTP | MCP over stdio |

### Claude Desktop / Claude Code Config (Remote)

```json
{
  "mcpServers": {
    "rzp-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.razorpay.com/mcp",
        "--header",
        "Authorization: Basic <Base64(key:secret)>"
      ]
    }
  }
}
```

### Claude Desktop Config (Local Docker)

```json
{
  "mcpServers": {
    "razorpay-mcp-server": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "RAZORPAY_KEY_ID", "-e", "RAZORPAY_KEY_SECRET", "razorpay/mcp"],
      "env": {
        "RAZORPAY_KEY_ID": "your_key_id",
        "RAZORPAY_KEY_SECRET": "your_key_secret"
      }
    }
  }
}
```

---

## 2. Complete Tool Inventory (45+ tools)

### Payments (6 tools)
| Tool | Description | Remote |
|------|-------------|--------|
| `capture_payment` | Change status from authorized to captured | Yes |
| `fetch_payment` | Fetch payment details by ID | Yes |
| `fetch_payment_card_details` | Card details for a payment | Yes |
| `fetch_all_payments` | List all payments with filtering/pagination | Yes |
| `update_payment` | Update notes field of a payment | Yes |
| `initiate_payment` | **S2S payment with saved method (token)** -- supports UPI collect, UPI intent, saved cards | Yes |

### Payment OTP (2 tools)
| Tool | Description | Remote |
|------|-------------|--------|
| `resend_otp` | Resend OTP for payment authentication | Yes |
| `submit_otp` | Submit OTP to complete payment | Yes |

### Payment Links (6 tools)
| Tool | Description | Remote |
|------|-------------|--------|
| `create_payment_link` | Create standard payment link | Yes |
| `create_payment_link_upi` | Create UPI-specific payment link | Yes |
| `fetch_all_payment_links` | List all payment links | Yes |
| `fetch_payment_link` | Fetch payment link details | Yes |
| `send_payment_link` | Send link via SMS or email | Yes |
| `update_payment_link` | Update a payment link | Yes |

### Orders (5 tools)
| Tool | Description | Remote |
|------|-------------|--------|
| `create_order` | Create a new order | Yes |
| `fetch_order` | Fetch order by ID | Yes |
| `fetch_all_orders` | List all orders | Yes |
| `update_order` | Update an order | Yes |
| `fetch_order_payments` | All payments for an order | Yes |

### QR Codes (7 tools)
| Tool | Description | Remote |
|------|-------------|--------|
| `create_qr_code` | Create UPI/Bharat QR code | Yes |
| `fetch_qr_code` | Fetch QR code by ID | Yes |
| `fetch_all_qr_codes` | List all QR codes | Yes |
| `fetch_qr_codes_by_customer_id` | QR codes for a customer | Yes |
| `fetch_qr_codes_by_payment_id` | QR codes for a payment | Yes |
| `fetch_payments_for_qr_code` | Payments received via a QR code | Yes |
| `close_qr_code` | Close a QR code | **No** (local only) |

### Refunds (6 tools)
| Tool | Description | Remote |
|------|-------------|--------|
| `create_refund` | Create a refund | **No** (local only) |
| `fetch_refund` | Fetch refund details | Yes |
| `fetch_all_refunds` | List all refunds | Yes |
| `update_refund` | Update refund notes | Yes |
| `fetch_multiple_refunds_for_payment` | All refunds for a payment | Yes |
| `fetch_specific_refund_for_payment` | Specific refund for a payment | Yes |

### Settlements (6 tools)
| Tool | Description | Remote |
|------|-------------|--------|
| `fetch_all_settlements` | List all settlements | Yes |
| `fetch_settlement_with_id` | Settlement details | Yes |
| `fetch_settlement_recon_details` | Settlement reconciliation report | Yes |
| `create_instant_settlement` | Create instant settlement | **No** (local only) |
| `fetch_all_instant_settlements` | List instant settlements | Yes |
| `fetch_instant_settlement_with_id` | Instant settlement details | Yes |

### RazorpayX Payouts (2 tools)
| Tool | Description | Remote |
|------|-------------|--------|
| `fetch_all_payouts` | Fetch all payout details with A/c number | Yes |
| `fetch_payout_by_id` | Fetch payout by ID | Yes |

### Tokens (2 tools)
| Tool | Description | Remote |
|------|-------------|--------|
| `fetch_tokens` | Get saved payment methods by customer/contact | Yes |
| `revoke_token` | Revoke a saved payment method | Yes |

### Registration Links (1 tool)
| Tool | Description | Remote |
|------|-------------|--------|
| `create_registration_link` | Auth link for subscription registration | **No** (local only) |

### Integration Helpers (2 tools)
| Tool | Description | Remote |
|------|-------------|--------|
| `detect_stack` | Detect project language/framework | Yes |
| `integrate_razorpay_checkout` | Generate checkout integration code | Yes |

**Total: 45 tools (41 available on remote, 4 local-only)**

---

## 3. The `initiate_payment` + `submit_otp` Flow (S2S)

This is the most interesting capability for an AI agent. The MCP server exposes the S2S (server-to-server) payment flow:

1. **`initiate_payment`** -- Creates a payment using:
   - Saved card token (no card number needed)
   - UPI VPA (collect flow -- sends request to user's UPI app)
   - UPI intent (returns `upi://pay?...` deep link)
   - Amount, order_id, customer details

2. **Response contains `next` actions:**
   ```json
   {
     "razorpay_payment_id": "pay_XXX",
     "next": [
       {"action": "otp_generate", "url": "..."},
       {"action": "redirect", "url": "..."}
     ]
   }
   ```
   For UPI intent flow, response includes the deep link:
   ```json
   {"razorpay_payment_id": "pay_XXX", "link": "upi://pay?pa=merchant@upi&am=100&cu=INR"}
   ```

3. **`submit_otp`** -- For card payments, submits the OTP to complete 2FA
4. **`resend_otp`** -- If OTP not received

**CRITICAL LIMITATION:** This is a *merchant receiving payments* flow. The Razorpay account holder is the merchant. The "customer" is the person paying. An AI agent could theoretically:
- Create an order on its own Razorpay merchant account
- Generate a UPI intent link
- Send it to Rajesh via Telegram
- Rajesh taps to pay
- Money goes INTO Rajesh's Razorpay merchant account (minus 2% fee)

This is circular and pointless for paying external merchants like Swiggy/Zomato.

---

## 4. Consumer vs Merchant: The Fundamental Problem

### What the MCP Server IS
- A **merchant dashboard automation tool**
- Lets a merchant's AI agent manage incoming payments, refunds, settlements
- Every tool operates on the merchant's Razorpay account

### What the MCP Server IS NOT
- A consumer payment API
- A way for an AI agent to pay arbitrary merchants from a user's bank account
- A UPI initiator for consumer transactions

### KYC Requirements for a Razorpay Account
- Individuals and sole proprietors CAN sign up
- Personal savings account accepted (no current account needed)
- Documents: PAN card, Aadhaar, bank proof
- Approval: 2-7 working days, some instant eKYC
- Can start accepting test payments immediately, live after KYC

---

## 5. Payment Links & QR Codes -- The "Self-Pay" Workaround

### How It Could Work for Annie

```
Annie decides Rajesh needs to pay ₹847 for Swiggy order
  |
  v
Annie creates a Razorpay Payment Link (via MCP or Python SDK):
  client.payment_link.create({
    "amount": 84700,  // in paise
    "currency": "INR",
    "description": "Swiggy order - Dinner",
    "upi_link": True,
    "customer": {"contact": "+91XXXXXXXXXX"},
    "notify": {"sms": True}
  })
  |
  v
Returns: short_url = "https://rzp.io/i/XXX"
  |
  v
Annie sends link to Rajesh via Telegram
  |
  v
Rajesh taps -> opens payment page -> pays via UPI/card
  |
  v
Money goes to Rajesh's Razorpay account (minus 2% TDR)
  |
  v
Rajesh manually transfers to himself? NO. Money is already his.
```

**PROBLEM:** This doesn't actually pay Swiggy. It just collects money from Rajesh into his own Razorpay account. This is **not a payment solution** -- it's a self-collection tool.

### QR Code Alternative (Same Problem)

```python
client.qrcode.create({
    "type": "upi_qr",
    "usage": "single_use",
    "fixed_amount": True,
    "payment_amount": 84700,
    "description": "Swiggy dinner order",
    "close_by": unix_timestamp_15_min_from_now
})
# Returns image_url with QR code
```

Types: `upi_qr` or `bharat_qr`. Can be single-use or multiple-use. Amount in paise. Min expiry 15 minutes, max 2 hours.

**Same fundamental problem:** QR code receives payment INTO the merchant (Rajesh's) account.

---

## 6. RazorpayX -- The Payout Path

RazorpayX is Razorpay's business banking product. Unlike the payment gateway (which receives money), RazorpayX **sends money**.

### Capabilities
- **Payouts** to bank accounts (NEFT/IMPS/RTGS) and UPI VPAs
- **Payout Links** -- send a link, recipient claims money
- **Fund accounts** -- manage beneficiary details
- **Contacts** -- manage payees (vendors, employees)

### API for Creating a Payout

```
POST /v1/payouts
{
  "account_number": "<YOUR_RAZORPAYX_ACCOUNT>",
  "fund_account_id": "fa_XXX",
  "amount": 84700,
  "currency": "INR",
  "mode": "UPI",       // or IMPS, NEFT, RTGS
  "purpose": "payout",
  "queue_if_low_balance": false,
  "reference_id": "swiggy_order_123"
}
```

### Limits
- UPI: up to ₹1 lakh per transaction (NPCI limit)
- IMPS: up to ₹5 lakh per transaction
- NEFT: no per-transaction limit
- Processed 24x7 for UPI and IMPS

### MCP Server Coverage
The official MCP server only has **read** tools for payouts:
- `fetch_all_payouts` -- list payouts
- `fetch_payout_by_id` -- payout details

**No `create_payout` tool in the MCP server.** Would need to use the Python SDK directly.

### Requirements for RazorpayX
- **Business account required** -- not available for individuals
- Complete business KYC (PAN, GST, bank account)
- Current account with RazorpayX
- **NOT suitable for personal use**

---

## 7. Razorpay SDKs

| SDK | Package | Stars | Language | Maturity |
|-----|---------|-------|----------|----------|
| **Python** | `pip install razorpay` | 171 | Python 3.5+ | Mature, well-documented |
| **Node.js** | `npm install razorpay` | 235 | JavaScript | Mature |
| **Go** | `github.com/razorpay/razorpay-go` | 55 | Go | Mature (MCP server uses it) |
| **Java** | Maven `com.razorpay` | -- | Java | Mature |
| **PHP** | `composer require razorpay/razorpay` | -- | PHP | Mature |
| **Ruby** | `gem install razorpay` | -- | Ruby | Available |

### Python SDK Resources

```python
import razorpay
client = razorpay.Client(auth=("<KEY_ID>", "<KEY_SECRET>"))

# All available resources:
client.payment       # Payments, S2S, OTP
client.order         # Orders
client.refund        # Refunds
client.payment_link  # Payment Links (standard + UPI)
client.qrcode        # QR Codes (UPI + Bharat)
client.customer      # Customers
client.subscription  # Subscriptions
client.invoice       # Invoices
client.settlement    # Settlements
client.transfer      # Route/Transfers
client.token         # Saved payment tokens
client.virtual_account  # Smart Collect
```

---

## 8. Authentication Model

### API Key Pair
- **Key ID** (`rzp_test_XXX` or `rzp_live_XXX`) -- identifies the merchant
- **Key Secret** -- authenticates the merchant
- Generated at https://dashboard.razorpay.com/ > Settings > API Keys
- Secret shown only once at creation time
- Used as HTTP Basic Auth: `Authorization: Basic base64(key_id:key_secret)`

### Test vs Live Mode
- Test keys (`rzp_test_XXX`) -- sandbox, no real money
- Live keys (`rzp_live_XXX`) -- production, real transactions
- Test mode is free and has no transaction limits

### OAuth (for platform integrations)
- OAuth 2.0 available for marketplace/platform models
- Allows accessing sub-merchant accounts
- Not relevant for personal use

### MCP Remote Server Auth
- Base64-encode `key_id:key_secret`
- Pass as `Authorization: Basic <token>` header
- Token rotation handled by Razorpay for remote server

---

## 9. Pricing

### Payment Gateway (Receiving Payments)
| Method | Fee | Notes |
|--------|-----|-------|
| UPI | 0% (free for <₹25L monthly) | Tiered after ₹25L |
| RuPay Debit | 0% MDR | Government mandate |
| Domestic Cards | ~2% + GST | Visa/Mastercard |
| Net Banking | ~2% + GST | All banks |
| Wallets | ~2% + GST | PayTM, PhonePe, etc. |

### Payment Links
- No additional fee on top of gateway TDR
- Free to create, charged only when payment succeeds

### QR Codes
- UPI QR: 0% for small merchants
- Same gateway TDR for card/net banking payments

### RazorpayX Payouts
- UPI payout: ₹5-10 per transaction (varies by plan)
- IMPS: ₹5-15 per transaction
- NEFT: ₹2-5 per transaction
- Payout Links: additional fee

### Free Tier
- No setup fee, no AMC
- Test mode is completely free
- You only pay per-transaction TDR when going live
- No minimum commitment

---

## 10. Agentic Payments -- The Future Path

### What's Live (Closed Pilot)

#### Razorpay + NPCI + Anthropic (Claude)
- **Announced:** Feb 20, 2026 at India AI Impact Summit
- **Mechanism:** UPI Reserve Pay (SBMD) -- user pre-authorizes spending limit per merchant
- **Spending cap:** Up to ₹10,000-15,000 per merchant authorization
- **How it works:**
  1. User sets spending limit for Swiggy/Zomato/Zepto on their UPI app
  2. AI agent (Claude) discovers products, builds cart via MCP
  3. Agent triggers payment within authorized limit -- NO PIN needed
  4. User retains full visibility, can revoke anytime
- **Live merchants:** Zomato, Swiggy, Zepto
- **Status:** Closed User Group (CUG). Cannot sign up as a general user.
- **Early access:** https://razorpay.typeform.com/to/KnIhwFxM

#### Razorpay + NPCI + OpenAI (ChatGPT)
- **Announced:** October 2025
- **Same UPI Reserve Pay infrastructure**
- **Initial merchant:** BigBasket
- **Status:** Pilot, broader rollout "in coming months"

#### Razorpay + Sarvam AI (Voice Commerce)
- **Announced:** March 24, 2026
- **Multilingual voice commerce** in Indian languages (Hindi, Hinglish, etc.)
- **First deployment:** Swiggy food ordering on Indus App
- **Auth model:** Upfront authentication, ₹10,000 spending cap, merchant bears liability for wrong orders
- **Status:** Early access, developer signups open

#### Gnani.ai + Razorpay (Enterprise Voice Collections)
- **Announced:** Feb 26, 2026
- **Use case:** AI voice agent collects payments during calls (EMI, bills)
- **Scale:** 10M+ calls/day
- **Mechanism:** Agent generates UPI payment link or UPI collect request mid-call
- **Status:** Live in production for enterprise customers

### Developer Integration Path (NOT yet available)

Razorpay has announced "Agent Studio" for developers to build agentic payment experiences. As of April 2026:
- No public API for agentic payments
- No SDK for UPI Reserve Pay
- Must apply for early access via typeform
- Expected to use MCP server as the integration layer
- 20+ merchant partners rolling out (per Harshil Mathur, March 26, 2026)

---

## 11. Community MCP Servers

### harshilmathur/razorpay-mcp
- **Author:** Harshil Mathur (Razorpay co-founder)
- **Language:** Python
- **Status:** Personal/prototype -- likely the precursor to the official server
- **Tools:** Payments, refunds, orders, customers, payment links, subscriptions, settlements

### LightHeads/razorpay-mcp (Unofficial)
- **URL:** https://github.com/LightHeads/razorpay-mcp
- **Language:** TypeScript/Node.js
- **Package:** `npm install -g razorpay-mcp@0.1.4`
- **Stars:** 2
- **Transport:** stdio + SSE server
- **Tools:** getAllPayments, getAllOrders, getAllSettlements, getAllRefunds, getAllDisputes

### Shubham7995/mcp-india (Multi-Service)
- **URL:** https://github.com/Shubham7995/mcp-india
- **Package:** `@mcp-india/razorpay` (npm)
- **Tools:** 18 tools -- payments, orders, settlements, subscriptions, invoices, customers, dashboard summary
- **Bonus:** Also includes Zoho CRM, GST India, Stripe, HubSpot, Airtable servers

### hahahamid/razorpay-mcp
- **URL:** https://github.com/hahahamid/razorpay-mcp
- **Language:** Unknown
- **Tools:** Payments, orders, refunds, settlements

### guglxni/VyapaarClaw (AI CFO)
- **URL:** https://github.com/guglxni/VyapaarClaw
- **Purpose:** AI CFO for Indian SMBs using Razorpay MCP
- **37 tools:** Budget control, vendor verification, risk scoring, compliance, payouts
- **Uses Razorpay remote MCP at `https://mcp.razorpay.com/mcp`**
- **Includes:** Fraud detection, GST validation, trial balance, income statement
- **Architecture reference** for how to build governance around payment MCP

### bugmagnet28/mcp-server-razorpay
- **URL:** https://github.com/bugmagnet28/mcp-server-razorpay
- **Tools:** Orders, payments, refunds, subscriptions, payment links

### Razorpay Blade MCP (Design System)
- **Package:** `@razorpay/blade-mcp` (npm)
- **Purpose:** NOT a payment MCP -- it's Razorpay's design system MCP for building UIs with AI
- **Completely unrelated to payments**

---

## 12. What This Means for Annie

### Can Annie Use Razorpay MCP?

| Use Case | Feasible? | How |
|----------|-----------|-----|
| **Accept payments from others** | Yes | If Rajesh registers as sole proprietor |
| **Pay Swiggy/Zomato via MCP** | **No** | MCP is merchant-side only |
| **Generate payment links for Rajesh** | Technically yes, but pointless | Rajesh would pay himself |
| **Create QR codes** | Same -- receives money, doesn't pay | Circular |
| **Automated refunds** | Yes (local only) | If Rajesh is accepting payments |
| **Track payments/settlements** | Yes | Dashboard automation |
| **RazorpayX payouts to merchants** | Requires business account | Not for personal use |
| **Agentic payments (Reserve Pay)** | **Not yet** | CUG only, no public API |

### Practical Verdict for Annie

**DO NOT USE Razorpay MCP for Annie's payment use case.** The entire architecture assumes you are a merchant receiving payments, not a consumer making them.

**WAIT FOR:** Razorpay Agentic Payments (UPI Reserve Pay) to exit closed pilot. When it does:
- Rajesh pre-authorizes spending limits per merchant in his UPI app
- Annie uses the MCP server's agentic payment tools to trigger payments
- No PIN needed, within authorized limits
- This is THE path for autonomous AI agent payments in India

**CURRENT BEST PATH (unchanged from RESEARCH-AGENTIC-PAYMENTS.md):**
1. Annie automates ordering via Swiggy/Zomato MCP + ADB
2. Sends UPI deep link or "pay now" notification via Telegram
3. Rajesh taps to pay (human-in-the-loop)
4. Annie confirms order status

### Architecture Reference Value

Even though Razorpay MCP doesn't solve Annie's payment problem, it provides excellent patterns:
- **VyapaarClaw** -- governance layer around payment MCP (budget enforcement, approval gates)
- **Gnani.ai integration** -- voice AI + MCP for mid-conversation payments
- **Tool design** -- read/write tool separation, remote server with write restrictions

---

## Sources

- [Official Razorpay MCP Server (GitHub)](https://github.com/razorpay/razorpay-mcp-server)
- [Razorpay MCP Docs](https://razorpay.com/docs/mcp-server/)
- [Razorpay Remote MCP 2.0 Blog](https://razorpay.com/blog/razorpay-remote-mcp-2-0-the-next-leap-in-ai-powered-payments/)
- [Razorpay + NPCI Agentic Payments for Claude](https://razorpay.com/blog/agentic-payments-and-npci/)
- [Razorpay Agentic Payments for Voice AI](https://razorpay.com/blog/razorpay-agentic-payments-voice-ai/)
- [Razorpay Agentic Payments Landing Page](https://razorpay.com/agentic-payments/)
- [Shashank Kumar (Razorpay) MCP Launch Announcement](https://x.com/shashank_kr/status/1916426439785848867)
- [Razorpay + NPCI + OpenAI Pilot (BusinessToday)](https://www.businesstoday.in/tech-today/news/story/razorpay-npci-openai-launch-pilot-for-agentic-payments-where-ai-powered-shopping-meets-upi-497545-2025-10-09)
- [Razorpay + Sarvam AI Voice Commerce (Business Standard)](https://www.business-standard.com/technology/tech-news/razorpay-sarvam-ai-partnership-voice-based-online-shopping-payments-126032400389_1.html)
- [Gnani.ai + Razorpay Voice Payments (Business Standard)](https://www.business-standard.com/technology/tech-news/gnani-ai-razorpay-launch-agentic-ai-platform-for-in-call-upi-payments-126022600639_1.html)
- [Razorpay Python SDK (GitHub)](https://github.com/razorpay/razorpay-python)
- [Razorpay QR Code API Docs](https://razorpay.com/docs/api/qr-codes/create/)
- [Razorpay Payment Link API Docs](https://razorpay.com/docs/api/payments/payment-links/create-standard/)
- [RazorpayX Payouts API Docs](https://razorpay.com/docs/api/x/payouts/)
- [VyapaarClaw AI CFO (GitHub)](https://github.com/guglxni/VyapaarClaw)
- [mcp-india Multi-Service MCP (GitHub)](https://github.com/Shubham7995/mcp-india)
- [LightHeads Unofficial Razorpay MCP (GitHub)](https://github.com/LightHeads/razorpay-mcp)
- [Razorpay KYC Documents](https://razorpay.com/docs/payments/business-types-kyc-documents/)
- [Razorpay Pricing (BuildMVPFast)](https://www.buildmvpfast.com/tools/api-pricing-estimator/razorpay)