Skip to content
Gaurav TiwariDocs

Razorpay

Version 1.0.0-beta.1 Updated November 8, 2026

Indian buyers pay by UPI first and card second, and RBI rules don’t let you charge a saved card whenever a renewal comes due. Each renewal needs a mandate the customer approved, a notice before every debit and a cap on the amount. So most stores give up and email a pay link every cycle.

The Razorpay module takes UPI, cards, netbanking and wallets through Razorpay Checkout, and renews subscriptions automatically through card e-mandates, UPI Autopay and eNACH. Renewals start a few days early to cover Razorpay’s pre-debit notice, then settle through Razorpay’s signed webhook. Refunds work in both directions.

Turn On the Gateway

  1. Switch on the Razorpay module under Stackless → Dashboard.
  2. Add your keys and webhook secrets under Stackless → Settings → Razorpay and save.
  3. Go to Downloads → Settings → Payments and switch on Razorpay (Stackless) under Active Gateways. Save.

Razorpay stays off the checkout until the selected mode has a key id and a key secret. The gateway is in Stackless Lite for EDD too. Automatic renewals need the Subscriptions module in Stackless for EDD.

Add Your API Keys

In the Razorpay Dashboard, open Account & Settings → API keys and generate keys once in Test mode and once in Live mode. The link on the settings screen goes straight there. Then fill in the Razorpay account section:

  • Test mode: uses your test keys, so no real money moves. On by default.
  • Test key id, Test key secret and Test webhook secret
  • Live key id, Live key secret and Live webhook secret

When you save, Stackless checks each key pair with Razorpay and shows any error. A test key id must start with rzp_test_ and a live one with rzp_live_. With the gateway switched on, a missing key pair or webhook secret for the selected mode shows an error too.

You can also set these as wp-config.php constants, which win over saved settings and hide their fields: STACKLESS_EDD_RAZORPAY_LIVE_KEY_ID, STACKLESS_EDD_RAZORPAY_LIVE_KEY_SECRET, STACKLESS_EDD_RAZORPAY_LIVE_WEBHOOK_SECRET and the same three with TEST in place of LIVE.

Connect the Webhook

Razorpay has no API for adding webhooks to your own account, so you add it by hand, once in Test mode and once in Live mode. In Account & Settings → Webhooks, choose Add New Webhook and paste https://yoursite.com/wp-json/stackless-edd/v1/razorpay/webhook. The Webhook section of the settings screen shows your exact URL. Pick a secret, tick these events and enter the same secret in the matching webhook secret field:

payment.authorized
payment.captured
payment.failed
order.paid
refund.processed
refund.failed
token.confirmed
token.rejected
token.cancelled
token.paused

The webhook confirms payments when a buyer closes the tab early, settles renewal debits, reports mandate approvals and rejections, and brings Razorpay refunds into EDD.

Each delivery’s X-Razorpay-Signature is checked against both secrets, and the one that matches sets the mode. Each event is applied once, and payments from other sites on the same Razorpay account are ignored.

What Buyers See

The Checkout section sets what buyers see:

  • Title: the payment method name at checkout. Default “UPI, cards, netbanking and wallets”.
  • Description: shown with the payment fields. Default “Pay securely with Razorpay.”
  • Checkout color: the accent color of Razorpay Checkout. Empty by default.

Clicking Purchase creates the pending order and opens a small payment page titled “Pay for order” with the order number. Razorpay Checkout opens on it straight away, with the buyer’s name and email filled in.

  • If the buyer closes Razorpay Checkout, Pay now opens it again. Choose another payment method goes back to checkout, where the same pending order is reused.
  • UPI shows as Intent or QR. UPI Collect, where the buyer types a UPI ID, isn’t offered.
  • EDD’s checkout has no phone field, so Razorpay Checkout asks the buyer for one.
  • After paying, Stackless checks Razorpay’s signature and reads the payment back. A payment whose amount or currency doesn’t match puts the order on hold with a note.
  • Paid orders go to your EDD success page. A payment that can’t be confirmed brings the buyer back to the payment page.
  • Test mode adds “Test mode: no real payment will be taken.”

One-time orders can use any currency on Razorpay’s international payments list that your account has switched on. Three-decimal currencies such as KWD and OMR are left out. Orders in rupees must be ₹1 or more. On the order screen, the transaction id links to the payment in the Razorpay Dashboard.

Turn On Recurring Payments

Automatic renewals use Razorpay recurring tokens, which need Razorpay’s Recurring Payments feature on your account. Razorpay switches it on when you ask its support team.

Until Razorpay switches it on, a subscription checkout that uses Razorpay fails with Razorpay’s error. If your account doesn’t have it, clear every choice in Renewal methods and save. Razorpay then hides itself at subscription checkouts, so buyers pay those with another gateway, and one-time orders still use Razorpay.

The Subscriptions section of the settings has three fields:

  • Renewal methods: the methods buyers can choose for subscriptions. Card, UPI Autopay and Bank account (eNACH), all on by default.
  • Plan-switch allowance (%): 0 to 500. The mandate covers the largest renewal plus this much, so upgrades keep renewing without a new mandate. Default 50.
  • Start renewal charges early (days): 1 to 7. Default 3.

A subscription checkout adds a Pay renewals with choice that lists only the methods whose ceiling covers the cart’s largest renewal. The buyer approves the mandate once in their bank or UPI app. If no method can cover the renewal, or the cart isn’t in rupees, Razorpay isn’t offered for that cart.

Mandate Maximum Amount

Every mandate has a maximum amount: the largest renewal on the order plus the plan-switch allowance, rounded up to whole rupees and held to the method’s ceiling. A ₹1,000 monthly plan with the default 50% allowance gets a ₹1,500 mandate.

MethodCeilingCharged at checkoutMandate lasts
Card₹15,000The order total, at least ₹1As long as the card
UPI Autopay₹99,999The order total, at least ₹110 years
Bank account (eNACH)₹1 crore₹0, the first payment follows separately10 years

₹15,000 is the RBI limit for card debits that don’t need the customer to approve each one. If Razorpay has approved your business for higher limits, raise the ceilings with a filter (see For Developers).

How Renewals Settle

Razorpay notifies the customer at least 24 hours before each debit, and the debit itself takes time: about a day for UPI, about 36 hours for cards and two working days for eNACH. So the renewal starts early, by the days in Start renewal charges early, and the webhook finishes it.

  1. On the early start date, Stackless creates the renewal order and asks Razorpay for a recurring debit on the saved mandate.
  2. Razorpay sends the customer its pre-debit notice. The order stays pending with a note that the debit was requested.
  3. When Razorpay captures the debit, the webhook marks the renewal paid. A failed debit marks it Failed with the reason, and your retry schedule takes over.
  • A debit is created once per attempt. If Razorpay can’t be reached, it’s retried up to 3 more times, 15, 30 and 45 minutes apart.
  • A renewal above the mandate’s maximum, or on a mandate that’s paused, cancelled or still unconfirmed, fails without a debit.

Renewals, Failed Payments and Retries covers what happens after a failure.

Free Trials and eNACH First Payments

  • A checkout with nothing to pay today, such as a free trial, still offers Razorpay and sets up the mandate. Cards and UPI take a ₹1 authorization that’s refunded straight away, with an order note. eNACH authorizes ₹0.
  • An eNACH mandate takes the bank about two working days to confirm. When the order has something to pay, it goes on hold with a note, and the first payment is debited once the bank confirms. The payment page tells the buyer this before they approve.
  • If the bank rejects or cancels the eNACH mandate, that order is marked Failed and the saved method is removed.

Saved Methods

  • Customers see their mandates in the Razorpay section of the Payment methods tab on the account page. They can make one the default or delete it.
  • Add a Razorpay payment method lets them pick a renewal method and approve it on the same payment page. Cards and UPI take ₹1, refunded once the method is saved. eNACH takes ₹0.
  • A mandate still waiting for the bank shows “(awaiting bank confirmation)”, and a paused one shows “(paused)”.
  • Deleting a saved method cancels the mandate at Razorpay, so it’s never debited again.
  • Saved Razorpay methods aren’t offered at checkout, because a debit on them lands a day later. They pay renewals and Post-purchase Offers.
  • Customers can change a subscription’s payment method from the subscription portal. Test and live mandates are kept apart.

Refunds

Refund from the EDD order screen, in full or in part. The refund form gets a Refund the payment in Razorpay box, ticked by default. Razorpay is called before EDD records the refund, so a refund Razorpay refuses stops there with the error. Untick the box to record the refund in EDD only.

Refunds made in the Razorpay Dashboard are recorded on the order once, through the webhook. A refund Razorpay can’t complete adds a note. The ₹1 trial authorization is never recorded as an EDD refund.

Billing Health

Razorpay reports to Billing Health: missing keys or webhook secret for the selected mode, test mode, renewal debits still pending after five days and webhooks that failed recently. Razorpay retries a failing webhook for 24 hours and then disables it, so check a webhook warning the same day.

Limits

  • Automatic renewals need Razorpay’s Recurring Payments feature on your account. Without it, clear Renewal methods so Razorpay stays off subscription checkouts.
  • Automatic renewals and saved methods are in Indian rupees only. In other currencies, Razorpay only shows for subscriptions whose Renewal mode is “Manual only (customer pays each renewal invoice)”.
  • Renewal orders stay pending for a day or more, and eNACH first payments wait on hold for the bank.
  • The webhook is added by hand, once per mode. Saved methods aren’t offered at checkout.
  • Razorpay Checkout opens on its own small payment page after Purchase, not inside your theme’s checkout page.
  • On a site Stackless treats as a copy of the live store, such as a staging clone, saved payment methods aren’t charged.
  • Razorpay can’t be duplicated with Payment Gateway Tools. Its mandates and customers belong to one Razorpay account.
  • Turn on Debug log under Advanced to write Razorpay activity to Downloads → Tools → Debug Log, tagged stackless-edd-razorpay_gateway. Errors are always logged. Keys never are.

For Developers

stackless_edd_razorpay_gateway_mandate_caps changes the per-method ceilings, in rupees, for businesses Razorpay has approved for higher limits:

add_filter('stackless_edd_razorpay_gateway_mandate_caps', function ($caps) {
    $caps['card'] = 100000; // ₹1,00,000
    return $caps;
});

stackless_edd_razorpay_gateway_currencies narrows the one-time currency list. stackless_edd_razorpay_gateway_webhook runs after each webhook is applied, with the event type, the event and the mode. Refunds created in code reach Razorpay only when stackless_edd_refund_at_gateway returns true. Copy any template from templates/razorpay_gateway/ to yourtheme/stackless-edd/razorpay_gateway/ to change the payment fields, the payment page or the account section.

Share

Was this helpful?

Still stuck? Open a support ticket