How to Build a Razorpay Payment Provider for Medusa v2 (UPI, Cards, Netbanking)

The v1 Razorpay plugin broke on upgrade because Medusa v2 replaced the plugin loader with a module system — PaymentProcessor became AbstractPaymentProvider, and the entire checkout workflow was rewritten. If you are porting an existing v1 integration, almost nothing carries over except the Razorpay API calls themselves. I am Manoj, commerce and ERP implementation lead at Mith Tech in Bengaluru, and wiring Indian payment rails into headless commerce stacks is the work we do every week.

Why there is no official Razorpay plugin

Medusa v2 shipped in late 2024 with a completely rewritten module system. The v1 plugin architecture — where payment plugins implemented PaymentProcessor and were loaded from medusa-config.js — was replaced by a module-based system where providers extend AbstractPaymentProvider and register through medusa-config.ts.

The original community Razorpay plugin (SGFGOV/medusa-payment-razorpay) was built for v1. When developers upgraded to v2, the plugin stopped loading entirely — the error was Unable to find the plugin 'medusa-payment-razorpay' (GitHub #9881). The maintainer has since published a v2-compatible package (@sgftech/payment-razorpay), and other community alternatives exist (@devx-commerce/razorpay, @tsc_tech/medusa-plugin-razorpay-payment, medusa-plugin-razorpay-v2), but none have official backing from the Medusa team.

This matters because Medusa's payment flow has specific requirements around session management, webhook handling, and the completeCartWorkflow that community plugins handle inconsistently. Building your own module gives you control over the parts that break — and they will break, particularly around webhook signature verification.

The payment flow — step by step

Every Razorpay payment through Medusa follows the same six-stage sequence, regardless of method. The specifics differ for UPI (async approval), cards (3DS redirect), and netbanking (bank redirect), but the Medusa side is identical.

The critical insight is that UPI and netbanking are asynchronous — the customer approves on a different device or in a bank redirect, and the result comes back via webhook. Medusa's default payment flow assumes synchronous card-style auth (GitHub #13837), which is why async methods fail if your webhook handler is not wired correctly.

The webhook signature problem

This is the single most common failure point for Razorpay integrations in Medusa v2, and it fails silently — your webhook returns 401, Razorpay retries a few times, gives up, and the customer's payment is captured but their cart never becomes an order.

The root cause: Razorpay's webhook signature verification requires the raw request body as a string. Medusa v2's API route layer parses the body as JSON before your handler runs (GitHub #9541, 39 comments). By the time your handler calls validateWebhookSignature(), the body has been parsed and re-serialised, which changes whitespace and key ordering — and the HMAC no longer matches.

The workaround: use JSON.stringify(req.body) for the raw body comparison. This works because Razorpay's webhook payloads use consistent JSON formatting. For a stricter approach, you can use a custom middleware to capture the raw body before parsing — but the JSON.stringify approach is what most production implementations use.

Double-capture risk

If you use both webhooks and the storefront handler callback to capture payments, you can accidentally capture twice (GitHub #13301, 94 comments — the highest-comment Stripe issue in the repo, but the same pattern applies to Razorpay). The fix: use an idempotency check in your capturePayment method. Query the Razorpay order status before calling capture — if it is already paid, return the existing payment rather than calling the capture API again.

Validating your configuration

Before writing any code, check your Razorpay credentials and module configuration. The three most common setup errors are: wrong key format (GitHub #1841), missing webhook secret, and sending amounts in rupees instead of paise.

Which payment methods to enable

India's payment landscape is not like the West. UPI accounts for over 60% of online transactions. Cards are secondary. Netbanking is the fallback for high-value B2B orders. Wallets (Paytm, PhonePe) are declining as UPI absorbs their use cases, but still matter for specific demographics.

The right mix depends on your business model:

UPI-specific considerations

UPI has a transaction limit of ₹1,00,000 for most banks (some allow up to ₹5,00,000 for merchant payments). Your checkout should validate the cart total against this limit before opening the UPI flow — otherwise the customer goes through the entire approval process on their phone only to get a rejection from their bank.

The Razorpay Checkout modal handles QR code display and VPA input automatically. For a better conversion rate, pre-fill the prefill.contact field with the customer's phone number from the shipping address — Razorpay can auto-detect linked UPI handles.

RBI tokenisation mandate

Since October 2022, the RBI requires that no payment aggregator or merchant store actual card numbers. Razorpay handles this through their token vault — when a customer saves a card, Razorpay stores a token and you reference that token for future payments. This is transparent if you use Razorpay Checkout (the modal handles it), but if you build a custom card form, you must use Razorpay's tokenisation API. Storing raw PANs is a compliance violation.

Building the payment provider module

The code recipe below covers four files: the payment provider service, the webhook handler, the storefront checkout component, and the module registration in medusa-config.ts.

// src/modules/razorpay/service.ts
import {
  AbstractPaymentProvider,
  PaymentProviderError,
  PaymentSessionStatus,
} from "@medusajs/framework/utils"
import Razorpay from "razorpay"

type RazorpayOptions = {
  key_id: string
  key_secret: string
  webhook_secret: string
}

class RazorpayPaymentProvider extends AbstractPaymentProvider<
  RazorpayOptions
> {
  static identifier = "razorpay"
  protected client_: InstanceType<typeof Razorpay>
  protected options_: RazorpayOptions

  constructor(container: Record<string, unknown>, options: RazorpayOptions) {
    super(container, options)
    this.options_ = options
    this.client_ = new Razorpay({
      key_id: options.key_id,
      key_secret: options.key_secret,
    })
  }

  async initiatePayment(input: {
    amount: number
    currency_code: string
    context: Record<string, unknown>
  }) {
    const order = await this.client_.orders.create({
      amount: input.amount, // already in paise
      currency: input.currency_code.toUpperCase(),
      receipt: input.context.cart_id as string,
    })

    return {
      id: order.id,        // razorpay_order_id
      data: { order_id: order.id },
    }
  }

  async getPaymentStatus(
    paymentSessionData: Record<string, unknown>
  ): Promise<PaymentSessionStatus> {
    const orderId = paymentSessionData.order_id as string
    const order = await this.client_.orders.fetch(orderId)

    switch (order.status) {
      case "paid":
        return PaymentSessionStatus.AUTHORIZED
      case "attempted":
        return PaymentSessionStatus.PENDING
      default:
        return PaymentSessionStatus.PENDING
    }
  }

  // ... capturePayment, refundPayment, cancelPayment
}

export default RazorpayPaymentProvider

What to know before you commit

Vendor lock-in. Razorpay is the payment layer — switching to Cashfree, PayU, or Juspay later means rewriting the payment provider module. The module interface is standardised (AbstractPaymentProvider), so the Medusa side stays the same, but the API calls, webhook formats, and error codes all change.

Settlement cycle. Razorpay settles to your bank account on T+2 for most payment methods. UPI and netbanking settlements can be T+1 with Razorpay's instant settlement feature (additional fee). Factor this into your cash-flow planning.

Refund processing. UPI refunds take 5–7 business days. Card refunds take 5–10 business days. Netbanking refunds can take up to 14 business days. Your order management workflow needs to handle the refund-pending state — Medusa marks the refund as processed immediately, but the customer does not see the money for days.

GST on Razorpay fees. Razorpay charges 2% + GST on card/netbanking transactions. UPI transactions are currently zero-MDR for merchants (as per RBI mandate), though Razorpay charges a platform fee on some plans. Your reconciliation must account for the 18% GST on payment gateway fees.

PCI-DSS compliance. If you use Razorpay Checkout (the hosted modal), Razorpay handles PCI-DSS compliance — card data never touches your server. If you build a custom card form and use the Razorpay.js tokenisation API, you are in SAQ A-EP scope. Most Indian D2C brands should use the hosted checkout.

Razorpay's payment rails work — the hard part is wiring them through Medusa's module system without the silent failures that eat orders. The flow debugger and config validator above catch the five issues that account for most integration failures. If your test webhook returns 200 and your cart becomes an order, the production setup is the same code with live keys and a verified domain.