Setting up Razorpay for an online store looks like a single task, "get the payment gateway working", but it is really five separate jobs that happen in a fixed order: create and verify your business account, generate test keys and prove the checkout works, generate live keys, connect a webhook so your store hears about payments even when the customer's browser closes, and finally run a short go-live test with real money. Most of the delays and support tickets that new sellers report come from doing these out of order, from mismatched names on documents, or from leaving test keys in a live store.
This guide is a step-by-step walkthrough for an Indian seller. It uses Razorpay's own documentation for every Razorpay-specific fact, shows which KYC documents are asked for by business type, explains the difference between test keys, live keys and the webhook secret, lists the webhook events a store should subscribe to, gives test card details for rehearsal, and ends with a go-live checklist, a troubleshooting table, and an explanation of how ShopMate handles the setup for merchants. Every Razorpay page cited was read on 3 October 2026; the dashboard menus and rules can change, so treat the live dashboard as the final authority.
Quick answer: (1) Sign up and complete KYC with documents that match your business type and bank account name. (2) Generate test keys and run test payments. (3) Once your account is activated, generate live keys; the secret is shown only once, so store it safely. (4) Add a webhook with a secret and the events your store needs. (5) Run a small real payment and a refund, then go live. Never share your key secret publicly and never leave test keys in a live store.
What you are setting up, in plain terms
Razorpay is an Indian payment gateway: a service that lets your store accept UPI, cards, netbanking and wallets and then settles the money to your bank account. Background on payment gateways in general is in Wikipedia's article on payment gateways. For your store, four things need to exist before a customer can pay:
- A verified Razorpay account in your business's name, with a bank account for settlements.
- API keys: a Key ID (public) and a Key Secret (private) that let your store create payment orders and verify results.
- A webhook: a web address on your store that Razorpay calls when a payment, refund or settlement event occurs, signed with a separate webhook secret.
- A tested flow: evidence, using test mode and then a small live payment, that an order moves correctly from "created" to "paid" and that a refund works.
Who does each step depends on your platform. On some platforms you paste the keys into a settings page yourself. On ShopMate, credentials are entered by the ShopMate team rather than by the merchant, which this guide explains in a later section. The Razorpay-side steps, KYC, keys and webhook configuration, are the same either way.
The five phases at a glance
| Phase | What you do | What it proves | Typical blocker |
|---|---|---|---|
| 1. Account and KYC | Sign up, submit business, identity and bank details | You are a real, verifiable business | Name mismatches between PAN, documents and bank account |
| 2. Test mode | Generate test keys; pay with test cards and UPI | The store can create orders and read results | Wrong keys pasted, or a mix of test and live keys |
| 3. Live keys | Generate live keys after activation | The store can take real money | Account not yet activated; secret not saved |
| 4. Webhook | Add a URL, secret and events | The store learns about payments independently of the browser | Wrong URL, slow response, secret mismatch |
| 5. Go-live test | Small real payment, then a refund | Money, order status and refund all behave | Skipping this step |
Phase 1: create your account and complete KYC
KYC, "know your customer", is the verification that lets a payment gateway pay money to a business. In India, the rules that payment aggregators follow come from the Reserve Bank of India; the RBI's directions for payment aggregators are published on the Reserve Bank of India website. As a merchant you do not need to read them, but they explain why a gateway asks for documents that a basic web service would not.
Choose the right business type first
The documents Razorpay asks for depend on the type of business you declare, so pick the type that matches your legal reality, not the one that looks easiest. Razorpay's documentation lists the documents by type (Razorpay, Business types and KYC documents, read on 3 October 2026). In summary:
| Business type | Documents the page lists |
|---|---|
| Individual or unregistered business | PAN card if the central KYC check fails; address proof such as Aadhaar, photo ID or passport, or DigiLocker verification; bank account number and IFSC code |
| Proprietorship | Two of: MSME/Udyam certificate, GST certificate, Shop and Establishment certificate, IEC, or a postpaid mobile bill; the proprietor's PAN; government-approved address proof of the proprietor; bank account number and IFSC code |
| Partnership | Partnership deed and registration certificate; business PAN; power of attorney for the authorised signatory; ultimate beneficial owner declaration for persons holding more than 10 per cent; bank account details |
| LLP | Certificate of incorporation, LLPIN or LLP deed; LLP PAN; power of attorney; ultimate beneficial owner declaration; bank account details |
| Private or public limited company | Memorandum and Articles of Association; business PAN; board resolution or power of attorney; ultimate beneficial owner declaration; bank account details |
| Trust | Trust deed or gazette notification, and trust registration certificate; trust PAN; power of attorney; beneficial owner declaration; bank account details |
| Society | Society registration certificate; society PAN; power of attorney; beneficial owner declaration; bank account details |
The page also notes that the PAN card details and the authorised signatory's address proof, such as an Aadhaar card or passport, should belong to the same person. It does not state verification timelines or bank-name matching rules, so any figure you read elsewhere for those should be treated as an estimate until Razorpay confirms it on your own account.
Which type suits a new small seller?
Many small sellers start as individuals or proprietors. A few practical points, none of which are legal advice:
- A proprietorship needs two business-identity documents from the list above. If you already hold a GST certificate and a Udyam certificate, you have two. If you hold neither, getting one is a prerequisite.
- Whatever name appears on your bank account is the name settlements will be paid to. Keep it consistent with the PAN and business documents you submit. Our guide to starting an online store in India covers how the registrations fit together; ask your accountant if you are unsure whether to register as a proprietorship, partnership or company.
- Registered entities such as LLPs and companies need more paperwork, including a power of attorney or board resolution naming the person who may act, and a declaration of owners. Start gathering these before you begin the form.
Prepare a KYC pack before you open the form
Doing the form in several sessions with documents hunted down mid-way is how errors creep in. Assemble a folder first.
- PAN of the person or entity as it will be declared, with the exact spelling of the name.
- Identity and address proof of the owner or authorised signatory, current and legible. Razorpay's page lists Aadhaar, photo ID, passport or DigiLocker verification for individuals and proprietors.
- Business documents for your type, from the table above.
- A bank account in the business's name, with the account number and IFSC code. Settlements will land here.
- Your website or store link. Razorpay's API-key documentation says live keys require verified website details, so have a working store address ready, with product pages, contact details and policy pages visible.
- Policy pages for returns, refunds, shipping and privacy, since reviewers and customers both look for them.
Common reasons KYC stalls
These are practical patterns rather than an official list, so use them as a checklist and not as a promise.
| Problem | Why it causes trouble | Fix |
|---|---|---|
| Name differs between PAN, bank account and documents | Verification compares the entity across records | Use the same legal name everywhere, or correct the record at the source before submitting |
| Document is blurred, cropped or expired | It cannot be read or is no longer valid | Rescan the full page in good light |
| Signatory's PAN and address proof belong to different people | Razorpay's page says they should be of the same person | Use one person's documents for both |
| Store is empty, under construction or password protected | The reviewer cannot see what you sell | Publish products, prices, contact details and policy pages before submitting |
| Business type declared incorrectly | The documents requested do not match your reality | Re-select the right type, then resubmit the matching documents |
| Bank account in someone else's name | Settlements must go to the business | Use an account in the business's or proprietor's name |
Phase 2: generate test keys and test the checkout
You do not need to wait for full activation to start testing. Razorpay's API-key documentation says test keys do not require website verification, while live keys do (Razorpay, API Keys, read on 3 October 2026). That means you can build and test the whole flow first, then take the account live.
What a key pair is
- Key ID. An identifier your store sends to Razorpay Checkout. It is not secret, but it still tells Razorpay which account the payment belongs to.
- Key Secret. A private value your server uses to authenticate API calls and to check payment signatures. It must never appear in website code, a public repository, a screenshot, a chat message or an email.
The documentation says the key secret is displayed only once at generation, so download or store it safely at that moment. If you lose it, you will need to regenerate the key.
Test mode versus live mode
Razorpay's Test and Live Modes documentation says test mode simulates payments and moves no real money, and that live mode processes real transactions (Razorpay, Test and Live Modes, read on 3 October 2026). The two modes have separate keys, and separate data in the dashboard. A payment made with a test key never appears among live payments, and the reverse is also true. This separation is useful, because you can rehearse every scenario without cost or risk. It is also the root of a common mistake: if a live store still holds test keys, customers see a working checkout but no real money is captured.
Test cards and UPI
Razorpay publishes test card details for rehearsal (Razorpay, Test card details, read on 3 October 2026). The page lists these examples, to be used only in test mode, with any future expiry date and a random CVV:
| Network | Example test card number |
|---|---|
| Visa | 4100 2800 0000 1007 |
| Mastercard | 5555 5100 0008 1006 |
| RuPay | 6527 6589 0000 1005 |
For the one-time password step, the page says that entering an OTP of 4 to 10 digits simulates a success, and an OTP shorter than 4 digits simulates a failure. That gives you a way to test both outcomes. Test UPI and netbanking behaviour is described on Razorpay's test-mode pages; look there for the current simulated UPI IDs rather than relying on a list copied elsewhere.
The test script
Run these scenarios in test mode before you touch live keys. Write down the result of each.
- Successful card payment. The order should become paid, stock should change, and a confirmation should be sent.
- Failed payment. Use an OTP shorter than four digits. The order should remain unpaid and the customer should be able to retry.
- Closed browser. Start a payment, complete it, then close the tab before the success page loads. After a minute, check whether the order still became paid through the webhook. This is the single most valuable test, and only works once the webhook in phase 4 is configured.
- Refund. Issue a full refund and a partial refund on test payments, and check the statuses.
- Wrong amount or tampered response. Ask your developer or platform whether the signature check rejects a modified response. You should not do this yourself on a live store.
- Cash on delivery and discount codes if you offer them, to confirm that totals are correct before payment.
Phase 3: generate live keys
Once Razorpay has verified your details and activated the account, you can generate live keys. According to the API-key documentation, live keys require verified website details, and the documentation describes the verification as taking about three business days (Razorpay, API Keys, read on 3 October 2026). Treat any timeline as an estimate; your own dashboard will show the current status.
How to generate and store them
- Switch the dashboard to Live Mode. Check the mode indicator, because test and live keys are generated separately.
- Open the account and settings area and find API Keys, then generate a key.
- Copy the Key ID and Key Secret immediately. The secret is shown only once.
- Store the secret in a password manager or a secrets vault that your business controls. Do not store it in a spreadsheet, a notes app on a shared device, or an email draft.
- Hand the keys to your platform through the route it provides. If a person must send them to you, use a secure channel agreed in advance, and never post them in a public ticket or group chat.
Rotating a key
If a secret is exposed, regenerate it. The documentation says regenerating a key needs an OTP and offers a choice of deactivating the old key immediately or after 24 hours. Immediate deactivation shuts the door at once but may fail live payments that use the old key until the new key is in place. A 24-hour overlap gives you time to update the store without downtime. Choose immediate deactivation when you suspect misuse, and the overlap when it is routine hygiene. Our guide to how an ecommerce platform with Razorpay built in works explains why the platform must be ready to accept a new key without a redeploy.
Never mix modes
A frequent error is a Key ID from one mode paired with a Key Secret from the other, or a store that uses test keys on the production site. The symptom is usually an authentication error on order creation, or a store that appears to work but never shows money in the live dashboard. If anything is unclear, confirm in the dashboard which mode each key was generated in.
Phase 4: set up the webhook
A webhook is how Razorpay tells your store about events in the background. Without it, your store relies on the customer's browser to report a successful payment. That works until a customer on a weak mobile connection pays through a UPI app and never returns to your page. The money has moved, but your order still shows unpaid.
Add the webhook
Razorpay's webhook documentation describes the process (Razorpay, Set up webhooks, read on 3 October 2026):
- In the dashboard, go to Accounts and Settings, then Webhooks, and choose to add a new webhook.
- Enter the webhook URL. It must be publicly reachable, and the documentation recommends HTTPS.
- Enter a secret. It is optional in the form but recommended, and it is a different value from your API key secret. It is used to sign every message so your store can check that it truly came from Razorpay.
- Select the events to receive.
- Enter an alert email, so you hear about delivery failures.
- Save, then trigger a test payment and check that your store logs the event.
Delivery rules to know
- Respond fast. The documentation says your endpoint should reply with a 2xx status within 5 seconds. Do heavy work after replying.
- Retries. If your endpoint does not respond successfully, Razorpay retries for up to 24 hours, after which the webhook is disabled. A long outage can therefore turn the webhook off, so check it after any downtime and re-enable it.
- Duplicates. Because of retries, the same event can arrive more than once. Your store should handle repeats without double-processing.
- Signature. Razorpay signs the body with your webhook secret using HMAC-SHA256. Background on the construction is on Wikipedia's HMAC article. Your store must compute the same signature from the raw body and compare it before trusting the message.
Which events to subscribe to
Subscribe only to events your store handles, since unhandled events are noise. A store that tracks payments, refunds, settlements and disputes will typically need these:
| Event | Why it matters to a store |
|---|---|
| payment.captured | Confirms money is captured; mark the order paid |
| payment.failed | Records the failed attempt and its reason |
| refund.created, refund.processed, refund.failed | Tracks each refund through to completion or failure |
| settlement.processed | Records which payments a bank credit covers |
| payment.dispute.created, under_review, action_required, won, lost, closed | Shows a chargeback, its deadline and its outcome |
| payment_link.paid, expired, cancelled | Updates orders or invoices paid through a payment link |
That list matches the events ShopMate's Razorpay webhook endpoint accepts, as found in its source code. Anything else that Razorpay sends is acknowledged and ignored.
What a webhook URL looks like on a multi-store platform
If a platform hosts many stores, each store needs its payments matched to the right merchant. One way is to put a store identifier in the webhook address, so the platform knows whose secret to use before reading the body. ShopMate's endpoint works this way: it reads the store from a query parameter on the webhook URL, falls back to identifying the store from the payment record in the payload, and verifies the HMAC-SHA256 signature using that store's webhook secret. A request with a missing or wrong signature is rejected with an "unauthorised" response.
The practical consequence is that you should copy the exact webhook URL that your platform gives you, including any parameters. Do not trim the query string, and do not reuse one store's URL for another.
Phase 5: enable payment methods and check settlement details
Payment methods
Razorpay Checkout can present several methods. Which of them appear depends on what is enabled on your account, so review the list in the dashboard and enable the ones your customers use. For most Indian stores the core set is UPI, cards and netbanking, with wallets and pay-later options as extras. Our guide on accepting UPI payments on your online store goes into UPI specifically. When you decide, think about failure and fees rather than only reach: more methods can lift conversion but each has its own failure modes and costs.
Settlement account and schedule
Razorpay's settlement documentation says the standard cycle for domestic payments is T+2 working days from capture, subject to bank approval and variation by business vertical and risk factors, and that an Instant Settlements option can reduce the wait on request (Razorpay, Settlements, read on 3 October 2026). Confirm the following on your own account:
- The bank account that receives settlements is yours and is spelled the way your documents spell it.
- Your actual settlement cycle, which may differ from the standard one.
- Who receives settlement emails, so a failed settlement does not go unnoticed.
Fees and tax on fees
Razorpay's charges depend on the payment method and your plan, and they change. Read the current rates on Razorpay's pricing page instead of relying on a number from a blog, including this one. GST is charged on gateway fees; the worked example below uses an assumed fee only to show how the arithmetic works.
A worked example: what lands in the bank
The figures below are illustrative assumptions, not Razorpay's rates. A merchant captures one payment of ₹1,180 with an assumed gateway fee of 2 per cent and 18 per cent GST on the fee.
| Line | Calculation | Amount |
|---|---|---|
| Payment captured | ₹1,180.00 | |
| Gateway fee (assumed 2%) | 2% × ₹1,180 | −₹23.60 |
| GST on fee (18%) | 18% × ₹23.60 | −₹4.25 |
| Net settled | 1,180 − 23.60 − 4.25 | ₹1,152.15 |
The 18 per cent on ₹23.60 is ₹4.248, shown rounded to ₹4.25. Over thousands of payments such small amounts add up, so book the fee and its tax as an expense and expect the bank credit to be smaller than your sales. Our guide to GST compliance for ecommerce sellers covers how to reconcile this each month.
The go-live checklist
Run through this list on the day you switch to live keys. Print it if you like.
- Razorpay account is activated and shows live mode.
- Live Key ID and Key Secret are saved in your secrets store.
- Live keys are loaded in the store and no test key remains anywhere in the store's configuration.
- The webhook is saved with HTTPS, a secret that differs from the API secret, the events from the table above, and an alert email.
- The webhook secret in Razorpay matches the secret stored in your platform.
- The settlement bank account is correct.
- Return, refund, shipping and privacy policy pages are published and linked from the checkout.
- Prices on the site are correct and include GST as you intend.
- You have placed one small real order, paid with your own UPI or card, and watched it become paid.
- You closed the browser mid-payment on a second small order and checked that the webhook still marked it paid.
- You have issued a refund on a small real payment and watched its status change.
- You have noted the day the first settlement should arrive and you will check it.
Why a small real payment matters
Test mode proves the code path, not the account. A real payment proves that your account is activated, your keys are live, your webhook is reachable, and money reaches your bank. Keep the amount small, pay it yourself, and refund it afterwards. Remember the refund timelines: Razorpay's refund documentation describes normal speed as taking 5 to 7 business days and an optimum speed that tries an instant route first and falls back to normal if it cannot (Razorpay, Refund speed, read on 3 October 2026).
Troubleshooting: when something does not work
| Symptom | Likely cause | What to check |
|---|---|---|
| Checkout does not open, or order creation fails | Wrong or mixed keys, or a missing amount or currency | Key ID and secret from the same mode; server logs for the error returned |
| Payment succeeds but the order stays unpaid | Webhook not configured, wrong URL, or signature mismatch | Webhook URL, secret on both sides, delivery log in the Razorpay dashboard |
| Webhook shows failures | Endpoint slow, down or returning errors | Respond with 2xx within 5 seconds; check uptime; re-enable after an outage |
| Webhook was disabled | Failures continued for 24 hours | Fix the endpoint, then re-enable it and replay missed events if your platform can |
| Live store shows no real payments | Test keys still in use | Dashboard mode and which keys are saved in your store settings |
| Customer paid but money missing in bank | Not yet settled, held or failed settlement | Settlement status and schedule in the dashboard |
| Signature verification fails for genuine payments | Wrong secret, or the body was altered before checking | Verify against the raw body with the correct secret |
| KYC marked incomplete | Document or name mismatch | The reason shown in the dashboard, then resubmit corrected documents |
Security habits that protect your money
- Treat the Key Secret like a bank password. Razorpay's documentation warns not to share it. Anyone holding it can call the API as your account, within the permissions of the key.
- Keep secrets out of code. They belong in encrypted configuration or a secrets manager, not in a repository or a front-end file.
- Verify on the server. Razorpay's integration steps call the signature check on the server a mandatory step (Razorpay, Integration steps, read on 3 October 2026). A browser-side check can be bypassed.
- Limit who can see the dashboard. Give staff the least access they need and remove access when someone leaves.
- Use strong login protection on the Razorpay account itself, and an email address you control.
- Rotate on suspicion. If a secret may have been exposed, regenerate it at once.
- Watch refunds and settlements. Unexpected refunds or a changed settlement bank account are warning signs.
For the full lifecycle of orders, signatures, webhooks, refunds and disputes, see our guide to ecommerce SaaS in India with Razorpay built in.
How ShopMate handles Razorpay setup
ShopMate's public pages say that online payments run on Razorpay and that settlements go directly to the merchant's own Razorpay account, managed through the merchant's own Razorpay dashboard (ShopMate, read on 3 October 2026). ShopMate also describes a 7-day free trial, followed by a demo call, a digital agreement and assisted setup of 5 to 7 business days (ShopMate pricing). Payment setup sits inside that assisted onboarding.
What this looks like in the product
These points come from ShopMate's own code and admin screens, not from marketing copy:
- Per-store credentials. Each store has its own Razorpay configuration, and the key secret and webhook secret are stored encrypted.
- Entered by the ShopMate team. Credentials are created or updated by ShopMate's super-admin users. A merchant's own admin panel shows the payment configuration as read-only status, so you do not paste secrets into the store yourself. That reduces the number of people who handle your secret, but it also means you must send the keys to the ShopMate team through a secure channel they agree with you, never through a public message.
- Webhook verification. The webhook endpoint checks an HMAC-SHA256 signature using the store's webhook secret and rejects requests without a valid signature.
- Supported events. The endpoint handles the events listed in the table above: payment captured and failed, refunds, settlements, disputes and payment links.
- Admin visibility. The admin panel has a Razorpay area for payments, refunds, settlements, disputes and alerts.
What stays with you
- Your Razorpay KYC and activation. The account is yours, and Razorpay verifies you as the business. ShopMate cannot complete or speed up Razorpay's review.
- Generating keys and the webhook secret in your own Razorpay dashboard, and choosing a secure way to hand them over.
- Your settlement bank account and the fees Razorpay charges you.
- Your go-live test with a small real payment and refund.
Limits to know before you choose
- Razorpay is the payment gateway the platform supports. If you need a different gateway, ask before you commit; the product's payment configuration is built for Razorpay only.
- Because credentials are entered by the ShopMate team, changes such as rotating a key involve a request to them, not a self-service form. Ask how quickly they can apply a new key if you ever need to rotate in an emergency.
If these trade-offs suit your store, you can book a demo to see the payment screens, read the pricing page for the commission and GST terms, or learn more about ShopMate.
Frequently asked questions
How long does Razorpay activation take?
It depends on your documents and the review. Razorpay's API-key documentation mentions about three business days for verification of website details, but Razorpay's pages do not promise an overall activation time, so check your dashboard for the status and any reasons given.
Can I test without completing KYC?
Yes, to a point. Razorpay's documentation says test keys do not need website verification, so you can build and test the checkout in test mode first. Live payments need an activated account and live keys.
What is the difference between the Key Secret and the webhook secret?
The Key Secret authenticates your server's API calls and checks payment signatures. The webhook secret signs the messages Razorpay sends to your webhook address. Razorpay's webhook documentation says the webhook secret is different from the API key, so use separate values and keep both private.
I lost my Key Secret. What now?
The secret is shown only once. Regenerate the key, update your store with the new pair, and choose whether to deactivate the old key immediately or after 24 hours. Plan the change so live payments are not interrupted.
Why did my webhook stop working?
Razorpay retries failed deliveries for up to 24 hours and then disables the webhook. If your endpoint was down or returned errors for that long, open the webhook in the dashboard, fix the cause and re-enable it. Then check for orders that were paid during the outage.
Do I need a webhook if the checkout already tells my store about the payment?
You should have one. The checkout response depends on the customer's browser returning to your page, and that does not always happen. The webhook confirms the payment from Razorpay's side, which is why the setup steps treat it as part of going live and not as an extra.
Can I use my personal bank account?
That depends on the business type you declare and Razorpay's checks. For an individual or proprietor, the bank account is generally expected to be in the business owner's name. Use the account that matches your documents and confirm with Razorpay if you are unsure.
Does the merchant or ShopMate enter the keys on ShopMate?
In ShopMate's product, credentials are entered by ShopMate's super-admin users; the merchant's admin panel shows the payment configuration read-only. Agree a secure way to share the keys during onboarding.
Conclusion
A clean Razorpay setup is mostly preparation. Choose the right business type, assemble a KYC pack with consistent names, rehearse in test mode, generate live keys only when the account is active, connect a signed webhook with the right events, and finish with a small real payment and refund. The checklist and troubleshooting table above turn that into a repeatable routine you can follow again when you add a second store or rotate a key.
Disclaimer
This article is general information, not legal, tax or financial advice. Razorpay's requirements, menus, fees and timelines change, so confirm them in your own Razorpay dashboard and with an accountant or adviser. Test card numbers are for test mode only. ShopMate publishes this article and has a commercial interest in the platform described. Competing and third-party products are described from their own published documentation and may have changed since the dates shown.
Sources and further reading
- Razorpay, Business types and KYC documents, read on 3 October 2026.
- Razorpay, API Keys, read on 3 October 2026.
- Razorpay, Test and Live Modes, read on 3 October 2026.
- Razorpay, Test card details, read on 3 October 2026.
- Razorpay, Set up webhooks, read on 3 October 2026.
- Razorpay, Integration steps, read on 3 October 2026.
- Razorpay, Settlements, read on 3 October 2026.
- Razorpay, Refund speed, read on 3 October 2026.
- Razorpay, Pricing, read on 3 October 2026.
- Wikipedia, Payment gateway, for background.
- Wikipedia, HMAC, for background on signature construction.
- Reserve Bank of India, for the regulator's published payment aggregator directions.
- ShopMate, home page and pricing page, read on 3 October 2026.
Next step
Want to see how a store goes from signup to its first live payment? Book a ShopMate demo, check the pricing and commission terms, or read about the team.