Lightweight ping that confirms the MCP server is live. No auth required.

Inputs: none

Output:

{ "status": "ok", "server": "CL Razorpay MCP Server" }

Creates an order that is required before initiating a payment on the frontend SDK.

Inputs:

• key_id (string, required) — Razorpay API key ID
• key_secret (string, required) — Razorpay API key secret
• amount (integer, required) — Amount in smallest currency unit (e.g. paise for INR; ₹500 = 50000)
• currency (string, required) — ISO 4217 currency code, e.g. "INR"
• receipt (string, optional) — Merchant receipt number (max 40 chars)
• notes (object, optional) — Key-value metadata to attach
• partial_payment (boolean, optional) — Whether partial payments are allowed (default: false)

Output:

{
  "id": "order_XXXXXXXXXX",
  "entity": "order",
  "amount": 50000,
  "currency": "INR",
  "status": "created",
  "receipt": "receipt_001",
  "created_at": 1690000000
}

Usage Example:

POST /mcp/razorpay/create_order

{
  "key_id": "rzp_test_XXXXXXXX",
  "key_secret": "XXXXXXXXXXXXXXXX",
  "amount": 50000,
  "currency": "INR",
  "receipt": "receipt_001"
}

Retrieves full details of a specific order.

Inputs:

• key_id (string, required)
• key_secret (string, required)
• order_id (string, required) — e.g. "order_XXXXXXXXXX"

Output: Full order object as returned by Razorpay API.

Retrieves a paginated list of orders, optionally filtered by creation timestamp.

Inputs:

• key_id (string, required)
• key_secret (string, required)
• count (integer, optional) — Number to return (default: 10, max: 100)
• skip (integer, optional) — Offset for pagination (default: 0)
• from_timestamp (integer, optional) — Unix epoch; fetch orders created after this
• to_timestamp (integer, optional) — Unix epoch; fetch orders created before this

Retrieves all payment attempts made against a specific order ID.

Inputs:

• key_id (string, required)
• key_secret (string, required)
• order_id (string, required) — e.g. "order_XXXXXXXXXX"

Updates the notes key-value map on an existing order.

Inputs:

• key_id (string, required)
• key_secret (string, required)
• order_id (string, required)
• notes (object, required) — Key-value pairs to set

Retrieves details of a specific payment.

Inputs:

• key_id (string, required)
• key_secret (string, required)
• payment_id (string, required) — e.g. "pay_XXXXXXXXXX"

Retrieves a paginated list of payments with optional timestamp filters.

Inputs:

• key_id (string, required)
• key_secret (string, required)
• count (integer, optional) — default 10, max 100
• skip (integer, optional) — default 0
• from_timestamp (integer, optional)
• to_timestamp (integer, optional)

Changes a payment from authorized to captured. Amount must exactly match the authorized amount.

Inputs:

• key_id (string, required)
• key_secret (string, required)
• payment_id (string, required) — e.g. "pay_XXXXXXXXXX"
• amount (integer, required) — Must match the authorized amount exactly
• currency (string, required) — e.g. "INR"

Updates the notes key-value map on an existing payment.

Inputs:

• key_id (string, required)
• key_secret (string, required)
• payment_id (string, required)
• notes (object, required)

Creates a refund for a captured payment. Omit amount for a full refund.

Inputs:

• key_id (string, required)
• key_secret (string, required)
• payment_id (string, required) — e.g. "pay_XXXXXXXXXX"
• amount (integer, optional) — Partial refund amount; omit for full refund
• speed (string, optional) — "normal" (default) or "optimum"
• notes (object, optional) — Key-value metadata
• receipt (string, optional) — Merchant receipt for the refund

Output:

{
  "id": "rfnd_XXXXXXXXXX",
  "entity": "refund",
  "amount": 50000,
  "payment_id": "pay_XXXXXXXXXX",
  "speed_processed": "normal",
  "status": "processed"
}

Inputs:

• key_id (string, required)
• key_secret (string, required)
• refund_id (string, required) — e.g. "rfnd_XXXXXXXXXX"

Inputs:

• key_id (string, required)
• key_secret (string, required)
• count (integer, optional) — default 10, max 100
• skip (integer, optional) — default 0
• from_timestamp (integer, optional)
• to_timestamp (integer, optional)

Inputs:

• key_id (string, required)
• key_secret (string, required)
• payment_id (string, required) — e.g. "pay_XXXXXXXXXX"
• count (integer, optional) — default 10
• skip (integer, optional) — default 0

Inputs:

• key_id (string, required)
• key_secret (string, required)
• refund_id (string, required)
• notes (object, required)

Inputs:

• key_id (string, required)
• key_secret (string, required)
• count (integer, optional) — default 10, max 100
• skip (integer, optional) — default 0
• from_timestamp (integer, optional)
• to_timestamp (integer, optional)

Inputs:

• key_id (string, required)
• key_secret (string, required)
• settlement_id (string, required) — e.g. "setl_XXXXXXXXXX"

Common Parameters

• count — Number of records to return (integer, 1–100, default 10)
• skip — Number of records to skip for pagination (integer, default 0)
• from_timestamp — Unix epoch integer; lower bound on created_at
• to_timestamp — Unix epoch integer; upper bound on created_at

Resource ID Formats

Order:

order_{alphanumeric}
Example: order_OE1jIbY9HrFaXw

Payment:

pay_{alphanumeric}
Example: pay_OE1jIbY9HrFaXw

Refund:

rfnd_{alphanumeric}
Example: rfnd_OE1jIbY9HrFaXw

Settlement:

setl_{alphanumeric}
Example: setl_OE1jIbY9HrFaXw

All tools require Razorpay API credentials. Here's how to obtain them:

Step 1: Sign Up / Log In

1. Go to Razorpay Dashboard
2. Sign up or log into your account

Step 2: Generate API Keys

1. Navigate to Settings → API Keys
2. Click Generate Test Key for sandbox or Regenerate Live Key for production
3. Download or copy both Key ID and Key Secret immediately

Step 3: Use Credentials Per Request

Pass key_id and key_secret in every tool call. The server uses HTTP Basic Auth (key_id as username, key_secret as password) on each request.

Step 4: Required Permissions

Ensure your Razorpay account has:

• payments:read — Read payment details
• payments:write — Capture and update payments
• orders:read — Read order details
• orders:write — Create and update orders
• refunds:read — Read refund details
• refunds:write — Create and update refunds
• settlements:read — Read settlement details

Refer to the Razorpay Authentication Guide for details.

Missing or Invalid API Key

• Cause: key_id or key_secret is missing, incorrect, or belongs to a different mode (test vs live)
• Solution:
  1. Re-copy credentials from the Razorpay Dashboard
  2. Ensure you are using test keys for sandbox and live keys for production
  3. Regenerate keys if they have been rotated

Insufficient Credits / Rate Limiting

• Cause: API calls have exceeded your account's rate limits
• Solution:
  1. Reduce request frequency
  2. Check Razorpay API Best Practices for rate limit guidance

Malformed Request Payload

• Cause: Required fields missing or wrong types
• Solution:
  1. Ensure amount is an integer in smallest currency unit (paise, not rupees)
  2. Ensure all required tool parameters are provided
  3. Verify currency is a valid ISO 4217 code

Payment Cannot Be Captured

• Cause: Payment is not in authorized state, or amount mismatch
• Solution:
  1. Check payment status with fetch_payment before capturing
  2. Ensure amount in capture_payment exactly matches the authorized amount

Refund Cannot Be Created

• Cause: Payment is not in captured state, or has already been fully refunded
• Solution:
  1. Verify payment status with fetch_payment
  2. Check existing refunds with fetch_refunds_for_payment

• Razorpay API Documentation — Official API reference
• Razorpay Authentication Guide — Auth setup guide
• Razorpay Orders API — Orders endpoint reference
• Razorpay Payments API — Payments endpoint reference
• Razorpay Refunds API — Refunds endpoint reference
• Razorpay Settlements API — Settlements endpoint reference
• FastMCP Docs — FastMCP specification