Razorpay MCP Server for Merchant Payments

Overview

Razorpay MCP Server is an open-source server implementation designed to simplify merchant onboarding, payouts, and reconciliation workflows. It provides a backend that integrates merchant data management, payment authorization, and settlement reconciliation into a single, extensible service suitable for platforms, marketplaces, and fintech applications.

The server exposes REST APIs for common merchant lifecycle operations, supports secure webhook handling for asynchronous events, and includes operational features such as health checks, metrics, and logging. Developers can deploy it as-is or use it as a reference implementation to build custom integrations on top of Razorpay’s payment APIs.

Features

• Merchant onboarding and KYC data management
• Payout orchestration and status tracking
• Reconciliation helpers and reporting endpoints
• Webhook receiver with signature verification and retry handling
• Pluggable storage (SQL-backed) and background workers
• Health checks, metrics (Prometheus-compatible), and structured logging
• OpenAPI/Swagger API documentation and Postman collection (when included)
• Docker and docker-compose friendly for local development

Installation / Configuration

Minimum steps to get the server running locally. Adjust variables to match your environment.

1. Clone the repository:

git clone https://github.com/razorpay/razorpay-mcp-server.git
cd razorpay-mcp-server

2. Create a .env file (example):

PORT=3000
NODE_ENV=development

# Database
DATABASE_URL=postgres://postgres:password@localhost:5432/mcp_db

# Razorpay credentials
RAZORPAY_KEY_ID=rzp_test_xxx
RAZORPAY_KEY_SECRET=your_secret

# App secrets
JWT_SECRET=supersecretkey
WEBHOOK_SECRET=webhook_secret

# Optional: Redis for background jobs
REDIS_URL=redis://localhost:6379

3. Run with Docker Compose (example):

# docker-compose.yml (excerpt)
version: "3.8"
services:
  db:
    image: postgres:13
    environment:
      POSTGRES_DB: mcp_db
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    ports: ["5432:5432"]

  redis:
    image: redis:6
    ports: ["6379:6379"]

  app:
    build: .
    env_file:
      - .env
    ports: ["3000:3000"]
    depends_on:
      - db
      - redis

Start:

docker-compose up --build

4. Run migrations and seed (example):

# If using a typical Node/ORM setup
npm install
npm run migrate
npm run seed
npm start

Notes:

• Replace environment values with production-ready secrets and credential management.
• Configure TLS/HTTPS and a reverse proxy in production.

Available Tools / Resources

• API documentation: /docs or /swagger (OpenAPI spec for interactive testing)
• Postman collection: included in the repo for quick endpoint testing
• Health & metrics endpoints:
  • GET /health — basic readiness/liveness
  • GET /metrics — Prometheus metrics (if enabled)
• Webhook verifier utility: function to validate Razorpay signature headers
• CLI scripts: migration, seed, and job worker commands (check package.json or Makefile)
• Example frontend/integration snippets demonstrating onboarding and payouts

API Reference (common endpoints)

Use Cases

• Merchant onboarding: Use the /api/merchants endpoint to capture business and KYC details, create a Razorpay account link or token, and maintain merchant state. Example flow: submit KYC → call Razorpay onboarding API → persist merchant id and onboarding status → notify merchant via email/webhook.

• Payouts for marketplaces: A platform can create payouts through /api/payouts. The MCP server handles idempotency, status tracking, and reconciliation references so settlements can be matched back to merchant accounts.

• Automated reconciliation: Upload or fetch statements and call /api/reconciliation to compare expected vs actual settlements. The server can generate mismatch reports and expose endpoints for export (CSV/JSON).

• Webhook-driven workflows: Configure Razorpay webhooks to /api/webhooks. The server verifies signatures, updates payout/merchant state, and pushes events to background workers for further processing (notifications, ledger updates).

• Auditing and reporting: Use built-in metrics and logs to monitor onboarding throughput, payout latency, failure rates, and reconciliation exceptions. Exportable reports help downstream accounting systems.

Getting Help

• Read the OpenAPI docs in the repo for request/response schemas.
• Check example scripts and Postman collection for integration patterns.
• Open issues or pull requests in the GitHub repository for bugs, feature requests, or configuration questions.