Connect Razorpay to Claude: Automate Payouts, Refunds & Settlements

If you need to connect Razorpay to Claude to automate vendor payouts, reconcile settlements, or trigger customer refunds, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's LLM tool-calling capabilities and Razorpay's REST APIs. You can either spend weeks building and maintaining this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Razorpay to ChatGPT or explore our broader architectural overview on connecting Razorpay to AI Agents.

Giving a Large Language Model (LLM) read and write access to your payment gateway is an engineering risk. You have to handle strict API keys, map massive JSON schemas for highly nested financial objects to MCP tool definitions, and deal with Razorpay's specific rate limits. Every time Razorpay updates an endpoint or adds a new webhook event, you have to update your server code, redeploy, and test the integration. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Razorpay, connect it natively to Claude, and execute complex financial workflows using natural language.

The Engineering Reality of the Razorpay API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Razorpay's APIs is painful. You are not just integrating "Razorpay" - you are integrating the Payments API, the Route API (for splits), the Payouts API (RazorpayX), and the Smart Collect API, all of which have different design patterns and error formats.

If you decide to build a custom MCP server for Razorpay, you own the entire API lifecycle. Here are the specific challenges you will face:

Complex Nested Financial Schemas Razorpay payloads are heavily nested. A single payment object contains sub-objects for acquirer_data, upi, card, wallet, and error_reason. If you pass this raw OpenAPI spec directly into Claude's context window as an MCP tool schema, you will exhaust your token limits and confuse the model. An MCP server must derive streamlined, LLM-friendly schemas that explicitly instruct the model on which fields are required and which are read-only.

Strict Rate Limiting and Backoff Logic Razorpay enforces strict rate limits based on your account tier and the specific endpoint being called. If your AI agent gets stuck in a loop attempting to bulk-reconcile settlements, Razorpay will return an HTTP 429 Too Many Requests error. It is critical to understand how this is handled: Truto does not retry, throttle, or apply backoff on rate limit errors. When Razorpay returns an HTTP 429, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. Your agent framework or client application is strictly responsible for implementing retry and backoff logic.

Flat Namespace Translation When an MCP client (like Claude) calls a tool, all arguments arrive as a single flat JSON object. However, Razorpay's REST API expects a strict separation between query parameters (like from and to timestamps for pagination) and request body payloads. Your MCP server has to split the LLM's flat arguments into the correct HTTP structure using the schemas' property keys before execution.

Instead of building this infrastructure from scratch, you can use Truto. Truto derives tool definitions dynamically from documentation, normalizes pagination, and exposes Razorpay's endpoints as ready-to-use, secure MCP tools.

How to Generate a Razorpay MCP Server with Truto

Truto creates MCP servers dynamically. Each server is scoped to a single integrated Razorpay account. You can generate a server URL via the Truto UI or programmatically via the API.

Method 1: Generating via the Truto UI

If you want to quickly give a local Claude Desktop instance access to your Razorpay sandbox or production account, the UI is the fastest path.

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected Razorpay account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can filter by methods (e.g., read-only access) or tags, and optionally set an expiration date.
5. Click Create and immediately copy the generated MCP server URL. (You will not be able to see the raw token again).

Method 2: Generating via the API

For production workflows - like provisioning isolated MCP servers for individual customer tenants or automated agent deployments - you should use the Truto API. This validates that tools are available, generates a cryptographically hashed token, stores the metadata in edge-based storage, and returns a ready-to-use URL.

Make a POST request to /integrated-account/:id/mcp:

curl -X POST https://api.truto.one/integrated-account/<RAZORPAY_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Razorpay Recon Agent Server",
    "config": {
      "methods": ["read", "write"],
      "tags": ["settlements", "payouts"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response will contain the unique server URL:

{
  "id": "mcp-7a8b9c0d",
  "name": "Razorpay Recon Agent Server",
  "config": {
    "methods": ["read", "write"],
    "tags": ["settlements", "payouts"]
  },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/f4a5b6c7d8e9f0..."
}

This URL contains the necessary routing and authentication material. The underlying raw token is never stored in plaintext by Truto; it is hashed before being written to the database.

How to Connect the MCP Server to Claude

Once you have the Truto MCP URL, connecting it to Claude requires zero additional code. You can configure it via the UI or directly via configuration files.

Method 1: Via the Claude UI

If you are using Claude for Web or Enterprise, you can add the server directly through the interface:

1. In Claude, navigate to Settings -> Integrations (or Connectors).
2. Click Add MCP Server.
3. Paste the Truto MCP Server URL you generated in the previous step.
4. Click Add. Claude will immediately execute an MCP initialize handshake, request the tools/list, and populate the model's context with your Razorpay operations.

Method 2: Via Manual Configuration File (Claude Desktop)

If you are running Claude Desktop locally or managing configuration via code, you can define the server in your claude_desktop_config.json file. Truto's endpoints support Server-Sent Events (SSE), meaning you can use the official @modelcontextprotocol/server-sse transport to connect directly to the HTTP endpoint.

Open your configuration file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows) and add:

{
  "mcpServers": {
    "razorpay_agent": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/f4a5b6c7d8e9f0..."
      ]
    }
  }
}

Restart Claude Desktop. The application will boot the SSE transport, connect to Truto, and pull down the integration schemas.

Hero Tools for Razorpay Automation

Truto dynamically derives MCP tools from your Razorpay integration documentation, translating them into snake_case commands with explicitly defined JSON Schemas. Here are the highest-leverage tools available for Razorpay.

list_all_razorpay_settlements

Retrieves all settlements from Razorpay. This tool automatically handles cursor-based pagination, allowing Claude to iterate through historical financial data. It returns critical fields like amount, status, fees, tax, and utr.

"Fetch the last 50 settlements from Razorpay. Identify any where the status is not 'processed' and list their UTR numbers and associated fees."

create_a_razorpay_payout

Executes a payout to a specific fund account. Requires strict formatting of parameters like account_number, fund_account_id, amount, currency, mode (e.g., IMPS, NEFT, RTGS), and purpose.

"Create a payout of 5000 INR using NEFT to fund account 'fa_123456789'. Set the purpose to 'vendor_bill' and add a narration 'Monthly infrastructure cost'."

list_all_razorpay_refunds

Retrieves a list of all refunds. Useful for customer support agents that need to verify if a refund was successfully processed, including checking the speed_requested versus speed_processed.

"Check our recent refunds. Find the refund associated with payment ID 'pay_AbCdEfGhIjKlMn' and tell me if it was processed instantly or normally."

create_a_razorpay_payment_link

Generates a standard Payment Link. This allows an AI agent to dynamically construct invoices or payment requests over chat or email. Returns the short_url which the agent can immediately pass to the end user.

"Generate a payment link for 1500 INR for customer John Doe (john@example.com, +919876543210). Set the description to 'Consulting fee for Q3'. Give me the short URL."

update_a_razorpay_customer_by_id

Modifies an existing customer record in Razorpay. This is highly useful for syncing contact updates from a CRM down to the payment gateway without manual data entry.

"Update the customer record for ID 'cust_XyZ123'. Change their contact phone number to '+919999999999' and ensure the email is updated to 'new.email@example.com'."

list_all_razorpay_disputes

Fetches chargebacks and disputes logged against your account. Returns reason_code, amount_deducted, phase, and evidence deadlines (respond_by).

"List all active disputes. Filter for any dispute in the 'open' phase where the respond_by deadline is within the next 48 hours, and summarize the reason codes."

To view the complete inventory of available Razorpay tools, resources, and detailed schema properties, visit the Razorpay integration page.

Workflows in Action

Exposing individual tools is just the foundation. The real power of an MCP server is enabling Claude to orchestrate complex, multi-step workflows autonomously.

Scenario 1: Automated Overdue Invoice Collection

The Problem: Sales ops spends hours tracking down customers with unpaid bills and manually generating payment links in the Razorpay dashboard.

The Prompt:

"Find the customer with ID 'cust_Alpha987'. Create a new payment link for 25000 INR for their overdue Q4 invoice. Once created, append the short_url to the customer's notes field."

How the AI executes it:

1. get_single_razorpay_customer_by_id: Claude calls this tool with id: "cust_Alpha987" to verify the customer exists and retrieve their exact email and phone parameters.
2. create_a_razorpay_payment_link: Claude passes the customer details, amount (2500000 paise), and currency ("INR") to construct the request. Razorpay returns the new link object.
3. update_a_razorpay_customer_by_id: Claude takes the short_url from the previous response and updates the customer's notes property with the newly generated link.

Scenario 2: Investigating a Failed Vendor Payout

The Problem: An operations manager needs to figure out why a specific vendor has not received their funds, requiring a dive into fund accounts and payout statuses.

The Prompt:

"Check the status of the payout made to account number '112233445566'. If the payout failed, check the linked fund account details to see if the IFSC code is valid, and summarize the error source."

How the AI executes it:

1. list_all_razorpay_payouts: Claude calls the tool filtering by the specific account_number. The tool returns the payout array.
2. Analysis: Claude reads the payload, checking the status and status_details object to identify that the status is failed due to a routing issue.
3. get_single_razorpay_fund_account_by_id: Claude extracts the fund_account_id from the failed payout and executes this tool to retrieve the bank_account sub-object.
4. Final Output: Claude formats a natural language response explaining that the payout failed in the 'clearing' step because the fund account holds an invalid or deprecated IFSC code.

Security and Access Control

Giving an AI write access to financial data requires strict boundaries. Truto provides several architectural controls to ensure your Razorpay MCP servers remain secure:

• Method Filtering: You can restrict a server strictly to read operations. By setting methods: ["read"] in the configuration, Truto will strip out create_a_razorpay_payout, update_a_razorpay_customer_by_id, and all other write tools during generation.
• Tag Filtering: Limit the scope of the server to specific functional areas. For example, using tags: ["settlements"] ensures the LLM can only see and access settlement data, completely blinding it to customers or payment links.
• Require API Token Authentication: By default, possessing the MCP URL grants access. By enabling require_api_token_auth, you force an additional middleware check. The connecting client must pass a valid Truto API token in the Authorization header, linking the MCP execution to an authenticated human user session.
• Ephemeral Servers: You can define an expires_at timestamp. Truto's distributed alarm system will automatically purge the server configuration, database records, and edge-stored tokens the second the timer hits zero.

Moving Past Manual Integration Maintenance

Building an integration layer between an LLM and an enterprise payment gateway is an exercise in managing technical debt. You are dealing with flat input namespaces against nested financial objects, strict pagination rules, and highly enforced rate limits.

By routing Claude through Truto's MCP infrastructure, you offload the authentication lifecycles, schema normalization, and dynamic tool generation entirely. Your engineers can focus on building the agent's core reasoning logic, rather than maintaining boilerplate API connector code.