Razorpay payment gateway setup runbook

Razorpay payment gateway setup runbook gives finance and implementation teams the exact Razorpay dashboard values, SquareOS gateway fields, webhook events, verification rules, refund proof, and go-live evidence needed before online checkout, payment links, mandates, refunds, disputes, or settlements are trusted in production.

What this page is for

Who should use it

Owner, implementation, finance admin, platform admin, support

Where to find it

Razorpay Dashboard / Account & Settings, SquareOS Admin / Razorpay Setting

Before you start

Razorpay payment gateway setup runbook: complete this runbook before a gym treats Razorpay Pay here, payment links, mandates, refunds, disputes, or settlements as production-ready in SquareOS.
Razorpay setup starts in Razorpay Dashboard / Account & Settings / API Keys and records dashboard mode, Key ID, Key Secret one-time capture, owner/admin access, and separate Test and Live key handling.
Razorpay webhook setup uses Account & Settings / Webhooks with SquareOS callback URL POST /commerce/webhooks/razorpay, webhook secret, active status, and subscribed payment.captured, payment.failed, payment_link.paid, payment_link.cancelled, refund.processed, settlement.processed, and dispute events used by the gym.
Razorpay capabilities setup records checkout enabled, payment links enabled, mandates/autopay enabled, refunds enabled, allowed payment methods, currency, merchant/account reference, settlement bank account readiness, and GST/business KYC status where exposed.
SquareOS Razorpay fields map provider values to Gateway Account provider RAZORPAY, account name, merchant reference, key ID, key secret credential, webhook secret, test mode, supports checkout, supports payment links, supports mandates, supports refunds, verified status, and active status.
Gateway go-live proof requires fake/test mode off for live certification, one low-value checkout or payment-link payment, x-razorpay-signature verification, matching provider payment id, order or payment link id, paid invoice, payment allocation, audit row, gateway-processing outbox/dead-letter check, and finance sign-off.
Razorpay refund proof requires a captured provider payment id, enabled refund capability, created refund id, refund webhook/status check, invoice/payment/refund row update, audit row, and finance approval before staff promise money returned.
Razorpay webhook verification must reject missing or mismatched x-razorpay-signature, wrong gateway account, duplicate event, unmatched payment/payment_link/refund id, and test-mode event sent to live account before money rows change.
Razorpay secret handling forbids exposing Key Secret, webhook secret, raw signature, raw webhook payload, dashboard screenshots with credentials, settlement bank details, or KYC documents in launch notes, mobile screens, support tickets, analytics, or crash logs.
If Razorpay portal labels differ from the runbook, extraction row must record dashboard path attempted, account owner, support ticket id, copied value, SquareOS field, masked secret handling, and verification action.

Daily workflow

Confirm the tenant, gym location, legal entity, Razorpay account owner, finance approver, and whether the work is for Test mode or Live mode before copying any values. Test and Live credentials must be recorded as separate extraction rows.
Open Razorpay Dashboard / Account & Settings / API Keys. In Test mode, generate or view test Key ID and capture the matching Key Secret only in the SquareOS write-only credential field or approved secret manager. In Live mode, generate Live keys only after the owner confirms KYC, settlement bank readiness, and finance approval.
Record Key ID, dashboard mode, owner/admin user, merchant/account reference, and secret-handling proof. If the Key Secret is not available because it was already generated earlier, rotate/regenerate through the approved owner path instead of asking staff to retrieve it from screenshots or chat.
Open Razorpay Dashboard / Account & Settings / Webhooks. Add the SquareOS public callback URL POST /commerce/webhooks/razorpay, enter a dedicated webhook secret, set an alert email, mark the webhook active, and subscribe only to the event families SquareOS and the gym will use.
For payment collection, subscribe to payment and payment-link events used by the tenant, including payment.captured, payment.failed, payment_link.paid, and payment_link.cancelled when payment links are enabled. For finance follow-up, add refund.processed, settlement.processed, and dispute events only when those workflows are enabled in SquareOS and support will reconcile them.
Record the Razorpay webhook id or dashboard row label, active status, alert email, subscribed events, webhook secret handling, and the configured callback URL. The webhook URL must be public HTTPS and must not be a localhost or blacklisted testing URL for production.
In SquareOS Admin / Razorpay Setting, create or update the Gateway Account with provider RAZORPAY, account name such as Razorpay Live - Main Gym, merchant reference, Key ID, write-only Key Secret, webhook secret, Test mode flag, checkout support, payment-link support, mandate support, refund support, verified status, and active status.
Configure Payment Modes so Online gateway modes point to the active Razorpay account. Checkout buttons should use supports checkout; payment-link buttons should use supports payment links; refund buttons should use supports refunds and finance policy.
Run the SquareOS Verify action for the gateway account. Then create a small internal invoice and test hosted checkout or a payment link. The pass condition is provider order/payment or payment_link id, verified x-razorpay-signature webhook, one paid invoice, one payment allocation, audit trail row, and no unresolved gateway-processing dead-letter for the same event.
For live certification, repeat the proof with Live mode credentials and a low-value real payment. Do not call the account production-certified from test-mode payment, fake mode, manually entered provider id, or dashboard screenshot alone.
For refunds, confirm refund support is enabled and finance approves the refund. Use a captured provider payment id, create a refund through the approved SquareOS/Razorpay path, capture refund id, verify refund webhook or status check, confirm refund/payment/invoice rows and audit row, and only then tell staff the money return is underway or completed.
For disputes and settlements, verify the subscribed webhook or sync path, gateway account, provider reference, settlement date, gross amount, fees, refunds, disputes, net amount, and bank-credit match before finance closes reconciliation. In the current backend, normal Razorpay payment webhook finalization updates payment and payment-link records; refunds are created through the refund API path, while settlement and dispute records are reconciled through explicit gateway sync/review actions.
Record official source references used for the extraction row: Razorpay API key and checkout integration docs, payment webhook setup docs, webhook signature validation docs, payment-link webhook docs, refunds API docs, and refunds webhook docs.

Watch out

Do not paste Key Secret, webhook secret, raw x-razorpay-signature, raw webhook payload, settlement bank details, KYC documents, or credential screenshots into launch notes, mobile screens, support tickets, analytics events, or crash logs.
Do not use the same webhook secret for terminal POS callbacks unless the terminal provider contract explicitly uses the same Razorpay payment webhook path. Terminal callbacks have their own POS terminal runbook.
Do not certify one Razorpay account and assume another branch, tenant, mode, or legal entity is covered. Test mode and Live mode need separate evidence rows.
Do not mark an invoice paid from a customer screenshot, dashboard screenshot, manually typed payment id, unsigned webhook, duplicate webhook, or unmatched provider reference.
Do not promise refunds before the refund id, provider status/webhook, SquareOS refund row, and finance approval are all recorded.
Do not let mobile apps collect gateway credentials or mutate gateway setup. Mobile can initiate backend-approved pay-online or payment-link actions and show read-only readiness only.

Use the left menu to open related pages in Start Here.
Use Ask Docs for questions that are already covered in this public documentation.