Razorpay Subscriptions integration: plans, UPI mandates, webhooks and reconciliation

How do you integrate Razorpay Subscriptions, step by step?

1. 1

   Create plans from code, one per tier, cycle and currency

   A Razorpay plan's amount and period cannot be edited once it exists, so a price change means a new plan. On countrydevs.com an admin creates a plan and our code creates the matching Razorpay plan and stores its ID. On Storafleet a sync job creates one plan per price version, billing cycle and currency, skips free and custom-priced plans, saves after every create so a failure cannot leave an unrecorded plan on Razorpay, and leaves existing IDs alone so a re-run creates nothing.

2. 2

   Create the subscription on the server

   The price comes from your own plan record, never from the browser. Set total_count to cover the plan's whole intended life, because it is the number of cycles Razorpay will charge; Storafleet asks for the longest Razorpay allows, 100 years. Put your app's name and your user ID in notes. A future start_at defers the first charge; Storafleet uses that to turn a customer's credit into free cycles. Refuse a second checkout while one is in flight, so a double click cannot create two mandates.

3. 3

   Verify the checkout response against the subscription

   For subscriptions Razorpay signs razorpay_payment_id, a pipe, then the subscription ID, with your key secret: the reverse of the order_id|payment_id string used for orders, and the subscription ID must come from your server, not from Checkout. Copying the order formula would reject every genuine payment. After the signature, fetch the subscription and act on its status, authenticated or active, rather than on the payment amount: with a future start the authentication payment is a refunded ₹5, not the plan price.

4. 4

   Receive webhooks on the raw body, store them, then answer

   Compute HMAC-SHA256 over the raw request bytes with the webhook secret and compare it in constant time. Save every signed event before doing any work and reply 200 inside Razorpay's 5-second window, then process it. On countrydevs.com a retry job replays failed events from the database at 1, 5 and 15 minutes, then 1 and 4 hours, and alerts an admin after the fifth failure. Razorpay documents the x-razorpay-event-id header as unique per event, which makes it the right key for spotting duplicates. Both apps key on it. countrydevs.com used to fall back to the payment or subscription ID, which made later events for the same payment look like repeats; since October 2026 it keys on the header and records each charge and refund once, whichever of its events arrives first.

5. 5

   Let one event write the money

   On Storafleet's checkout, payment.authorized, payment.captured and order.paid arrived before any subscription event, carrying an order ID we had never stored, and payment.captured and order.paid fire again on every renewal. We made subscription.charged the only handler that writes the invoice, the ledger entry and the new period end, keyed on the charge's order ID, and let payment handlers ignore orders they do not know. The charged handler takes the currency from the payment itself, after a first charge was once booked in the wrong currency because the subscription record had not been updated yet.

6. 6

   Branch plan changes on the mandate type

   Razorpay will not update a subscription authorised by UPI or e-mandate. On countrydevs.com an upgrade works out the unused part of the current cycle in paise, collects the difference as a one-off Razorpay order, and then moves the customer: in place for card mandates, or for UPI and every other method by cancelling the old subscription and creating a new one that starts when the paid period ends. The new tier applies as soon as the difference is captured. Razorpay's update page limits domestic-card subscriptions to offer changes, so our in-place card path still needs one run with a real domestic card in test mode.

7. 7

   Make every cancellation reach Razorpay

   Call Razorpay's cancel API from every path that ends a paid subscription: the customer's cancel, an admin's cancel, and a refund that ends access. If the call fails, record it and retry it on the next billing run. Razorpay cannot undo a cancellation, so 'resume' on a cancelled subscription has to open a fresh checkout for the same plan; only a paused subscription resumes in place.

8. 8

   Reconcile against Razorpay, not only from webhooks

   After four rounds of payment fixes on countrydevs.com we made Razorpay the source of truth and our database a cache of it. A billing page read pulls the subscription from Razorpay first, at most once every 5 seconds per user. Every subscribe, upgrade, downgrade, cancel or resume is followed by background reconcile passes at 2, 5, 10, 20, 45 and 90 seconds. Missing payments are rebuilt from the subscription's invoices, every difference is logged as a drift event, and a job at boot and every day checks the account's webhook subscriptions against the 23 events the code handles.