Razorpay Magento Integration — A Complete India + INR Setup Guide

1. Install the official Razorpay Magento module

Razorpay's razorpay/razorpay-magento package is on Packagist and mirrored on the Magento Marketplace^[2]. The Composer route is the only one to use in 2026 — Marketplace ZIP installs are deprecated and skip the lock-file pinning that keeps the SDK version stable across deploys.

Composer install

composer require razorpay/razorpay-magento
bin/magento module:enable Razorpay_Magento
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

The package pulls razorpay/razorpay (PHP SDK) and razorpay/curl as transitive dependencies. Force the latest with composer require razorpay/razorpay-magento:^4.6.

What ships in the module

The Hyvä Checkout adapter is a separate package — hyva-themes/magento2-razorpay^[3]. Install it after the official module on Hyvä storefronts.

2. Configure API keys and capture mode

Razorpay issues two key pairs per account — Test mode (rzp_test_) and Live mode (rzp_live_). Both live in the dashboard under Settings → API Keys. Never commit the Live secret.

Admin path

Stores → Configuration → Sales → Payment Methods → Razorpay. The fields that matter:

env.php injection (recommended)

<?php
// app/etc/env.php
'system' => [
    'default' => [
        'payment' => [
            'razorpay' => [
                'key_id' => getenv('RAZORPAY_KEY_ID'),
                'key_secret' => getenv('RAZORPAY_KEY_SECRET'),
                'webhook_secret' => getenv('RAZORPAY_WEBHOOK_SECRET'),
            ],
        ],
    ],
],

Magento reads from env.php first when the same path exists in core_config_data. The deploy script reads from the CI vault and exports the env vars before bin/magento runs.

Sandbox smoke test

curl -X POST https://api.razorpay.com/v1/orders \
  -u rzp_test_xxxxxxxxxxxxxx:test_secret_xxxxxxxxxxxxxx \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 50000,
    "currency": "INR",
    "receipt": "order_smoke_001"
  }'

A 200 response with an id field starting order_ means the key pair is valid. Amount is in paise — 50000 paise is ₹500. Currency must be INR for Indian-registered Razorpay accounts.

3. Webhook signature verification — the part that is not optional

Razorpay fires three webhooks every production storefront must handle — payment.captured, payment.failed, refund.processed. Each arrives with an X-Razorpay-Signature header computed as HMAC-SHA256(webhook_secret, raw_body)^[4]. The official verifier is correct — the trap is custom observers stacked on top that capture the order before the verifier runs, marking failed payments as paid.

Verifier signature pattern

<?php
// app/code/Panth/RazorpayHardening/Controller/Webhook/Verify.php
namespace Panth\RazorpayHardening\Controller\Webhook;

use Magento\Framework\App\Action\HttpPostActionInterface;
use Magento\Framework\App\Config\ScopeConfigInterface;
use Magento\Framework\App\Request\Http as HttpRequest;
use Magento\Framework\Controller\Result\JsonFactory;
use Magento\Store\Model\ScopeInterface;
use Psr\Log\LoggerInterface;

class Verify implements HttpPostActionInterface
{
    public function __construct(
        private HttpRequest $request,
        private ScopeConfigInterface $config,
        private JsonFactory $jsonFactory,
        private LoggerInterface $logger
    ) {}

    public function execute()
    {
        $rawBody = $this->request->getContent();
        $signature = $this->request->getHeader('X-Razorpay-Signature');
        $secret = $this->config->getValue(
            'payment/razorpay/webhook_secret',
            ScopeInterface::SCOPE_STORE
        );
        $expected = hash_hmac('sha256', $rawBody, (string)$secret);

        // Constant-time comparison — never use ===
        if (!hash_equals($expected, (string)$signature)) {
            $this->logger->warning('Razorpay webhook signature mismatch');
            $result = $this->jsonFactory->create();
            $result->setHttpResponseCode(400);
            return $result->setData(['status' => 'invalid_signature']);
        }

        $payload = json_decode($rawBody, true);
        $event = $payload['event'] ?? '';
        // Dispatch by event — payment.captured, payment.failed, refund.processed
        return $this->jsonFactory->create()->setData(['status' => 'ok']);
    }
}

The three events to dispatch on

Webhook URL registration and retries

In the Razorpay dashboard under Settings → Webhooks → Add New Webhook, set the URL to https://your-store.example/razorpay/webhook and tick only the three events above. order.paid and payment.authorized fire alongside payment.captured and cause double processing on auto-capture configs.

Razorpay retries failed deliveries on exponential backoff for 24 hours — 5s, 30s, 5m, 30m, 2h, 12h^[4]. The controller must respond with HTTP 200 inside 5 seconds. Move slow work (email, inventory adjust) into a Magento queue consumer.

4. RBI's 2-factor authentication mandate and the 3-step redirect

The Reserve Bank of India has mandated 2-factor authentication on all domestic card-not-present transactions since 2021^[5]. Razorpay handles the OTP for cards, bank login for NetBanking, and UPI PIN prompt for UPI — the storefront keeps the order pending across redirects and only finalizes on the webhook.

The 3-step flow

1. Customer clicks Place Order. Magento POSTs to /v1/orders and gets a razorpay_order_id, then opens the Razorpay Checkout iframe.
2. Customer picks UPI or Cards. Razorpay redirects to the bank's 2FA page (OTP for cards, UPI PIN for UPI).
3. Bank confirms. Razorpay redirects back to Magento's callback route with razorpay_payment_id and razorpay_signature. Magento verifies the signature, then waits for the payment.captured webhook to flip the order to processing.

Callback signature verification — different from webhook

The callback signature is HMAC-SHA256 of razorpay_order_id|razorpay_payment_id using the API key secret (not the webhook secret). Reusing the wrong secret is the most common silent failure.

<?php
// app/code/Panth/RazorpayHardening/Helper/CallbackVerifier.php
public function verify(string $orderId, string $paymentId, string $signature): bool
{
    $secret = $this->config->getValue(
        'payment/razorpay/key_secret',
        ScopeInterface::SCOPE_STORE
    );
    $expected = hash_hmac('sha256', $orderId . '|' . $paymentId, (string)$secret);
    return hash_equals($expected, $signature);
}

What can go wrong in the 2FA window

• Customer closes the tab during OTP entry — Magento has a pending order with no payment. The reconciliation cron must call /v1/payments?order_id=... after 15 minutes and cancel if no successful payment exists.
• OTP times out at the bank — Razorpay fires payment.failed. The webhook handler must move the order to canceled.
• Redirect URL fails but bank confirmed — money is debited, customer lands on a Magento 404. The webhook still arrives — the order is completed from the webhook path, not the callback path. Keep both routes working.

The reconciliation cron

curl -G https://api.razorpay.com/v1/payments \
  -u rzp_live_xxxxxxxxxxxxxx:live_secret_xxxxxxxxxxxxxx \
  --data-urlencode "from=$(date -v-30M +%s)" \
  --data-urlencode "to=$(date +%s)" \
  --data-urlencode "count=100"

The cron runs every 5 minutes, pulls the last 30 minutes of payments, and cross-checks against Magento's pending orders. Razorpay's Settlements → Reconciliation Report is the source of truth for daily numbers — never the Magento DB alone.

5. Subscriptions — UPI AutoPay and NetBanking recurring via the e-mandate flow

The default module handles single-payment orders. Recurring billing — subscription products, installments, donation auto-debits — needs the Razorpay Subscriptions API plus the e-mandate flow for UPI AutoPay and NetBanking recurring.

The Razorpay Subscriptions object model

UPI AutoPay e-mandate creation

curl -X POST https://api.razorpay.com/v1/subscriptions \
  -u rzp_live_xxxxxxxxxxxxxx:live_secret_xxxxxxxxxxxxxx \
  -H 'Content-Type: application/json' \
  -d '{
    "plan_id": "plan_MJ3kRzn4Yp8XQK",
    "customer_notify": 1,
    "total_count": 12,
    "start_at": 1748822400,
    "notes": {"magento_customer_id": "4271"}
  }'

The response includes a short_url field — the e-mandate auth page. Redirect the customer there on Magento Subscribe click. The UPI app prompts for an e-mandate approval (PIN + consent screen), and Razorpay fires subscription.activated on success.

The subscription webhooks to handle

{
  "event": "subscription.activated",
  "payload": {
    "subscription": {
      "entity": {
        "id": "sub_MJ3kPQrTzS9XJk",
        "plan_id": "plan_MJ3kRzn4Yp8XQK",
        "customer_id": "cust_MJ2jOPqRyT0WIj",
        "status": "active",
        "charge_at": 1751414400
      }
    }
  }
}

Magento creates the panth_subscription row on this webhook, links it to customer_entity, and schedules the next billing reminder. The recurring charge fires through subscription.charged — each charge generates a fresh Magento order via the same observer that handles one-off payments.

The UPI AutoPay PIN entry race

The UPI e-mandate consent screen has a 5-minute timeout. If the customer takes longer, the mandate fails silently and the subscription stays in created state forever. Poll GET /v1/subscriptions/<id> every 10 minutes for an hour; if still created after 60 minutes, cancel the local row and email the customer.

6. Settlement timing and refund liquidity planning

Razorpay settles to the merchant bank account on a rolling T+1 to T+3 schedule based on KYC tier^[6]. New accounts default to T+3; verified merchants drop to T+2; high-volume verified merchants negotiate T+1. The settlement timing affects refund liquidity and the Magento Pending dashboard.

Refund liquidity

If today's GMV is ₹1,000,000 and a ₹50,000 refund hits at T+0 — before any settlement has arrived — Razorpay funds the refund from the next settlement, debiting the merchant balance. New accounts can run negative if refunds exceed the unsettled balance.

Settlement reconciliation script

curl -G https://api.razorpay.com/v1/settlements/recon/combined \
  -u rzp_live_xxxxxxxxxxxxxx:live_secret_xxxxxxxxxxxxxx \
  --data-urlencode "year=2026" \
  --data-urlencode "month=5" \
  --data-urlencode "day=20" \
  --data-urlencode "count=1000" > rzp-settlement-2026-05-20.json

A nightly Magento cron pulls this JSON, joins to sales_order on razorpay_payment_id, and inserts a row into panth_settlement_reconciliation. The finance team queries that table instead of the live Razorpay dashboard.