Skip to main content

Tenant Onboarding — Razorpay

Audience: Hotel operators / tenant admins who want to enable online guest payments through KeyNova. Time required: ~15 minutes. Prerequisites: You are a KeyNova user with role ADMIN or SUPER_ADMIN, and you have (or are ready to create) a Razorpay account.

This guide walks through the self-serve flow for connecting a Razorpay merchant account to KeyNova. Once complete, guest payments from your booking engine, folio settlements, and payment links will route through your own Razorpay account — KeyNova never takes custody of the funds (Direct merchant model).

What "Direct merchant model" means

Settlements from Razorpay land in the bank account you registered with Razorpay, not in a KeyNova-controlled account. KeyNova orchestrates the payment and owns the ledger, audit, and reconciliation logic; it does not touch the money. PCI DSS scope stays contained — KeyNova is SAQ-A and never stores raw card data.

Step 1 — Create (or sign in to) a Razorpay account​

  1. Go to https://dashboard.razorpay.com.
  2. Sign up (new) or sign in (existing).
  3. Complete KYC — PAN, GSTIN, bank account, and business proof documents. Razorpay typically approves within 2–4 business days.
  4. Once live, switch the dashboard toggle (top-right) to Live Mode. If you are onboarding a sandbox / staging KeyNova environment, leave it on Test Mode.
Test vs Live keys

Razorpay keys are prefixed by mode. Test keys start with rzp_test_ and live keys start with rzp_live_. KeyNova validates the prefix against the mode you select and refuses mismatches.

Step 2 — Generate API keys in Razorpay​

  1. In the Razorpay dashboard, open Account & Settings → API Keys.
  2. Click Generate Key (Live Mode).
  3. Razorpay shows you Key Id and Key Secret exactly once. Copy both to a password manager immediately — the secret cannot be retrieved later.
  4. If you lose the secret, regenerate the key; you will update KeyNova via Rotate credentials in Step 7.

You now have:

  • key_id, e.g. rzp_live_AbCdEfGhIj1234
  • key_secret, e.g. 4Jg9PxQZ... (32–40 chars)

Step 3 — Open KeyNova's Payment Providers settings​

  1. Sign in to the KeyNova dashboard: https://<your-tenant>.keynovahotels.com.
  2. In the left navigation, open Settings.
  3. Click Payment Providers.

You see a list of connected accounts (empty on a fresh tenant) and an Add Merchant Account button.

Step 4 — Add a merchant account in KeyNova​

  1. Click Add Merchant Account.

  2. Fill in the form:

    FieldValue
    ProviderRazorpay
    ScopeAll properties (tenant-wide default) or Specific property (franchise / multi-entity)
    Property— (if Scope = Specific property, pick one)
    ModeLive (or Sandbox if this is a staging environment)
    Display namee.g. "Razorpay — Main"
    Key IDpaste the key_id from Step 2
    Key Secretpaste the key_secret from Step 2

  3. Click Validate & Save. KeyNova calls GET /v1/payments?count=1 against Razorpay to prove the keys work. On failure you see the specific Razorpay error (e.g. Invalid API key).

  4. KeyNova stores the credentials envelope-encrypted (AES-256-GCM under a per-row DEK wrapped by AWS KMS — see Modular Payments Architecture §5).

  5. On success, KeyNova displays the Webhook URL for this account:

    https://api.<your-env>.keynovahotels.com/api/webhooks/razorpay-gateway/<merchant_account_id>

    Copy it — you need it in the next step.

Exactly one account per scope

You can hold only one active account per (tenant, property, provider). Adding a second active account for the same scope returns 409 DUPLICATE_ACTIVE_ACCOUNT. Deactivate the old one first, or use a different property scope.

Step 5 — Register the webhook URL in Razorpay​

  1. Back in the Razorpay dashboard, open Account & Settings → Webhooks.

  2. Click + Add New Webhook.

  3. Paste the Webhook URL from Step 4.

  4. Choose a Secret — 32+ random characters. Razorpay uses this to HMAC the webhook body; KeyNova uses it to verify. Keep this value handy for the next step.

  5. Under Alert Email, enter the inbox that should receive Razorpay-side webhook delivery failures (operator, not developer).

  6. Under Active Events, enable the exact set KeyNova consumes:

    • payment.authorized
    • payment.captured
    • payment.failed
    • refund.processed
    • refund.failed
    • order.paid

    Do not enable anything else — KeyNova ignores extra events, but more events means more noise in the WebhookEvent audit log.

  7. Click Create Webhook.

Step 6 — Paste the webhook secret back into KeyNova​

  1. Return to KeyNova Settings → Payment Providers and open the account you just created.

  2. Click Add Webhook Secret.

  3. Paste the secret you set in Step 5.

  4. Click Save.

  5. Click Send Test Webhook. KeyNova triggers Razorpay's built-in test webhook feature and waits for round-trip delivery. You see:

    • ✅ Test successful — isActive flips to true; you're live.
    • ❌ Signature mismatch — the secret doesn't match. Rotate the secret in Razorpay and re-paste in KeyNova.
    • ❌ Timeout — the webhook URL isn't reachable. Check the URL is exactly what KeyNova provided (no trailing slash, correct environment).

Once the test passes, the account card shows a green Active badge. Your tenant is now accepting online payments via your Razorpay account.

Step 7 — Rotating credentials later​

You need to rotate keys if:

  • A staff member who knew the secret leaves the organization.
  • Razorpay shows a suspicious login or rotates your keys.
  • You are doing routine rotation (recommended every 12 months).
  1. Generate a new key pair in Razorpay (Step 2).
  2. In KeyNova, open the account and click Rotate credentials.
  3. Paste the new key_id and key_secret. KeyNova validates against Razorpay atomically — if validation fails, the old keys remain active.
  4. Click Save. Rotation is instant — there is no dual-key grace period.
  5. If you also rotated the webhook secret in Razorpay, paste the new secret via Rotate webhook secret.

Every rotation writes an AuditLog entry visible at Settings → Audit Log filtered by merchant_account.rotated. The entry records:

  • Who rotated (user id + role).
  • When (timestamp + IP address).
  • Key prefix before/after (e.g. rzp_live_AbCd • • → rzp_live_XyZw • •).
  • KMS key version used to encrypt.

The full secret is never logged — only the 6-character prefix, matching the platform-wide Pino redactor.

Troubleshooting​

"Credentials validation failed — Invalid API key"​

  • You copied the key from Test Mode but selected Live in KeyNova (or vice versa). Re-check the Razorpay mode toggle.
  • The key was revoked in Razorpay. Generate a new pair.
  • Extra whitespace around the pasted secret. Re-copy cleanly.

"Test webhook — signature mismatch"​

  • The secret in KeyNova doesn't match the one in Razorpay. Most commonly caused by a trailing newline when pasting. Rotate the secret in Razorpay and paste again, being careful not to include surrounding whitespace.
  • The webhook URL has an extra path segment (e.g. trailing /) and Razorpay is delivering to a 404. Confirm the URL is byte-exact.

"Test webhook — timeout"​

  • The wrong environment's URL was used. Staging URL pasted into Live Razorpay, or vice versa.
  • KeyNova api-gateway is down. Check status page.
  • Razorpay IPs are not reaching our ingress. If you are on a self-hosted KeyNova deployment, verify ingress whitelisting.

"Payments initiated but stuck in PENDING_USER_ACTION"​

See the operator troubleshooting appendix in Modular Payments Architecture §8. Most common cause: guest abandoned checkout — no action needed, the nightly reconciler will expire the attempt after 2 hours.

"Account deactivated unexpectedly"​

KeyNova auto-deactivates accounts after repeated ProviderAuthErrors (keys were rotated on the Razorpay side without a matching KeyNova rotation). Fix the upstream issue, then Rotate credentials — a successful validation re-activates the account.

"I need to move from Sandbox to Live"​

Mode is immutable after a successful payment — this is intentional, to prevent historical reinterpretation of test vs real money. Create a new LIVE account with your live keys, and then deactivate the sandbox account.

What happens next​

Once your account is active:

  • Booking engine deposits route through it automatically for all new bookings (after the PAYMENTS_V2_BOOKING_ENGINE feature flag flips for your tenant — Phase 1 of the migration plan).
  • Folio settlement can be collected online via Send Payment Link from the folio detail page.
  • Refunds are triggered from the reservation, folio, or payment-link detail pages and route automatically to the provider+account of the original attempt.
  • Metrics appear in Grafana under KeyNova Payments. The alert set is documented in the oncall runbooks under hmp-infrastructure/monitoring/runbooks/.

See also​