Razorpay

Razorpay Documentation Audit

Razorpay ships an llms.txt at both root and docs level and exposes a public Postman workspace, but the developer surface is undermined by structurally empty SDK sections, a broken Standard Checkout tutorial link, contradictory metadata between the two llms.txt files, a missing llms-full.txt that convention implies, and time-stamped copy (UPI Collect deprecation, IE warning, "May 2024 What's New") that has aged past its expiry date.

1. Every SDK / "Client Libraries" section renders with empty language slots (critical)

Location: /docs/build/llm-docs/api/sandbox-setup.md, /docs/build/llm-docs/payments/server-integration.md, /docs/build/llm-docs/payments/payment-gateway.md, /docs/build/llm-docs/payments/payment-gateway/web-integration/standard.md

Problem: Every Client Libraries / Server Integration block renders with the same pattern — seven rows of - **Integrate**: and - **GitHub Repo**: labels with no language names and no links populated. server-integration.md opens with "By using Razorpay Payment Gateway, you can integrate your server using the below listed languages:" and then lists seven entries that are completely blank. The Standard Checkout Prerequisites page does the same. The sandbox setup page tells developers "Refer to the relevant SDK documentation for specific instructions" and then shows no SDK names or links.

Consequence: A developer trying to start a server integration cannot tell which languages Razorpay actually supports, cannot click through to a GitHub repo, and cannot copy an npm install / gem install / composer require line. The "below listed languages" is literally empty. For an LLM coding agent, this is worse — there is no machine-readable list to fall back on, so the agent will guess package names. This breaks the first step of every server-side integration.

The fix: Populate every Client Libraries block with the canonical language list (Node.js, PHP, Python, Ruby, Java, .NET, Go) along with the install command and the GitHub URL for each. Add an SDK index page that all four locations include-by-reference so this never goes stale in three places at once.

2. Standard Checkout "Build Integration" link 404s on Razorpay's own marketing site (critical)

Location: /docs/build/llm-docs/payments/payment-gateway/web-integration/standard/build-integration.md

Problem: The Standard Checkout Prerequisites page lists three sequential steps: "1. Build Integration", "2. Test Integration", "3. Go-live Checklist". The Build Integration page returns Razorpay's marketing 404: "Congratulations, you've found the 404 page! You are seeing this page because this URL does not exist."

Consequence: The most common Razorpay integration path — Web Standard Checkout — has a broken Step 1. Developers following the Prerequisites flow click "Build Integration" and land on a marketing 404 with no path back into the integration tutorial. There is no redirect to a successor page.

The fix: Restore the build-integration.md page (or 301 redirect it to whatever replaced it), and run a link-check against the llm-docs tree in CI so a broken in-doc link blocks merge.

3. llms-full.txt is referenced by convention but returns 404 (significant)

Location: https://razorpay.com/docs/llms-full.txt

Problem: Razorpay publishes /llms.txt at both root and /docs/, signalling the docs are designed for LLM consumption. But the conventional companion /docs/llms-full.txt returns HTTP 404. The docs-level llms.txt already references "Implementation Bundles," instructions for LLMs, and a curated quick-start — but the long-form expansion file expected by agents is absent.

Consequence: Coding agents (Cursor, Claude Code, Windsurf) that look for llms-full.txt as the expanded corpus fall back to scraping HTML page by page, which is slow and lossy. Agents that do find the index also encounter contradictions between the two llms.txt files (see issue 4).

The fix: Either publish a real llms-full.txt that concatenates the API reference, errors, webhooks, and authentication content, or remove the implicit promise by aligning the index to only the files that exist.

4. Root and docs llms.txt disagree on "Last Updated" (significant)

Location: https://razorpay.com/llms.txt vs https://razorpay.com/docs/llms.txt

Problem: The root llms.txt declares Last Updated: 2026-03-02 and Generator: Razorpay. The docs-level llms.txt ��� which the root file directs LLMs to prefer for "implementation-level queries" — declares Last Updated: 30 April 2026 and Generator: Razorpay Docs Team. Two months of divergence between the file Razorpay itself says to trust and the file at the canonical root path.

Consequence: An agent reading both files has no way to know which index is authoritative. If the agent caches the root version, it may miss two months of changes (e.g., the May 2026 ICICI Debit Card EMI deprecation in the changelog). The date format also differs (2026-03-02 vs 30 April 2026), making programmatic comparison harder.

The fix: Generate both files from a single source of truth in the same build step, use ISO-8601 dates everywhere, and treat the root file as a thin pointer to /docs/llms.txt rather than a duplicate index with its own metadata.

5. Order ID in the errors sample contradicts the documented 14-character identifier rule (significant)

Location: /docs/build/llm-docs/errors.md and /docs/build/llm-docs/api/understand.md

Problem: The "Understand Razorpay APIs" page states: "The identifier is of 14 characters, alphanumeric and case-sensitive." The errors page sample response uses order_DBJKIP31Y4jl8 — which after stripping the order_ prefix is 13 characters, not 14.

Consequence: A developer (or an agent generating validation regex) writing input validation against the documented "14 characters" rule will reject Razorpay's own sample identifiers. This is exactly the kind of contradiction that fails silently — humans squint and move on, agents emit a strict regex that rejects valid IDs in production.

The fix: Either correct the sample to a real 14-character ID, or clarify the rule (e.g., "The identifier portion after the entity prefix is 14 characters" or "12–14 characters depending on entity type") to match what the API actually emits.

6. UPI Collect deprecation copy is written in the future tense after the cutoff has passed (significant)

Location: /docs/build/llm-docs/payments/changelog.md

Problem: The Feb 2026 changelog row reads: "[UPI Collect] flow is being deprecated effective 28 February 2026. Existing users must migrate to UPI Intent or UPI QR code to continue accepting UPI payments." Today is 2026-05-14 — more than two months after the cutoff — yet the page still talks about the deprecation as a pending event.

Consequence: A developer landing on this row today cannot tell from the copy whether UPI Collect is still alive, gone, or in a grace period. An agent summarising the Razorpay UPI surface will faithfully reproduce the "is being deprecated" wording and recommend an obsolete migration path. Time-bomb copy like this erodes trust in every other dated claim on the page.

The fix: Rewrite past-tense ("was deprecated on 28 February 2026"), link to the current UPI Intent / UPI QR migration guide, and add a build-time check that flags future-tense deprecation language whose date has passed.

7. Changelog has triplicate entries and an inconsistent product name (significant)

Location: /docs/build/llm-docs/payments/changelog.md

Problem: The June 2025 changelog row "Introduced Cash on Delivery as a payment method on the checkout page" appears three times back-to-back. Two of the three rows have a typo in the product column — "Payment Metods" instead of "Payment Methods" — so they would also not match a filter on the correct product name.

Consequence: The changelog is the contract for "what changed and when." Triplicated rows imply three separate releases, and the misspelled product name breaks any filter/index that groups by product. An agent summarizing the June 2025 release notes will report COD three times.

The fix: Deduplicate the row, fix the spelling, and add a uniqueness constraint or a build-time check on (month, product, description) so duplicate changelog rows can't be merged.

8. Webhook "Blacklisted Domains" list rules out the dev tools developers actually use (significant)

Location: /docs/build/llm-docs/webhooks/validate-test.md

Problem: The webhook page blocks ngrok.io, webhook.site, loca.lt, requestbin.com, hookbin.com, beeceptor.com, mockbin.org, and several others as webhook URLs. The recommended replacement is zrok with a link to docs.zrok.io. There is no in-page guidance on how a developer working on localhost should test webhooks day-to-day beyond a pointer to an external project.

Consequence: A new integrator following the quick-start cannot point Razorpay at the tunneling service they already have configured (ngrok being the most common). They land on this page mid-integration, discover their tool is blocked, and have to install and learn a new tool just to receive a test webhook. There is no documented allowlist mechanism for trusted dev URLs in your own account.

The fix: Either provide a Razorpay-hosted webhook inspector for test mode (mirroring Stripe's CLI listen flow), or document an account-scoped allowlist override. At minimum, expand the zrok walkthrough inline rather than punting to an external doc.

9. Webhook HMAC verification trail dead-ends at the empty SDK page (significant)

Location: /docs/build/llm-docs/webhooks.md and /docs/build/llm-docs/webhooks/validate-test.md

Problem: The webhooks overview describes signature verification at a conceptual level. The validate-test page says "We provide support for validating the signature in all of our language SDKs" and links back to server-integration.md — the same page flagged in Issue 1, where every language slot is empty. The Java snippet on the validate-test page is also a no-op template rather than runnable verification code.

Consequence: The single security-critical path the docs-level llms.txt insists on ("Always enforce ... HMAC SHA256 signature verification in code examples") has no working endpoint. A developer who wants to verify webhooks without an SDK cannot find a single complete HMAC-SHA256 snippet on either page; one who follows the SDK link lands on the empty page from Issue 1.

The fix: Inline a single canonical HMAC-SHA256 verification snippet (curl + a representative language) on the webhooks overview page, independent of the SDK list. Replace the no-op Java template on validate-test.md with a complete, runnable example.

10. "Best Practices" is three bullets and a 2-year-old "What's New" callout (minor)

Location: /docs/build/llm-docs/api/best-practices.md

Problem: The Best Practices page contains exactly three bullets (don't share your key secret, honour DNS TTL, SDKs handle DNS for you) followed by a "What's New" callout dated May 2024 — about two years older than the docs-level llms.txt's claimed "30 April 2026" update date. There is no guidance on idempotency keys, retries, signature verification placement, rate-limit-aware client design, or webhook ordering — all of which are mentioned in other pages but never gathered here.

Consequence: A developer searching "razorpay best practices" gets a page that under-delivers on its title and shows a 2-year-old "new" feature, undermining trust in the freshness of every other page.

The fix: Either rename the page to "API Key Hygiene & DNS Caching" or actually expand it: idempotency, retries with backoff (already mentioned under Rate Limiting — link it), HMAC verification, webhook handler patterns, server-side order creation (mentioned in llms.txt instructions but not surfaced here).

11. Authentication page repeats the same numbered steps verbatim with an embedded typo (minor)

Location: /docs/build/llm-docs/api/authentication.md

Problem: Under "Generate API Keys," the page lists steps 1–3 (log in, choose Test/Live mode, navigate to Account & Settings → API Keys → Generate Key). The "Live Mode API Keys" subsection then repeats the exact same 1–3 steps verbatim, along with a copy of the Watch Out warning. The Live Mode block adds only one new sentence ("you must enter the OTP"), which itself contains a typo: "to authroize the new user."

The fix consequence here is mostly the typo: "authroize" surfaces in any search query that hits the authentication page and looks unpolished on what is a security-sensitive page. The duplicated step list is wasted real estate but won't block an integration.

Consequence: The visible typo on the auth page is a small but real polish defect on a page developers visit early. The duplication makes it ambiguous which block is canonical when copy is updated later.

The fix: Collapse the two blocks into a single step list with a "Live mode also requires OTP authorization" callout. Fix the "authroize" typo.

12. Test-mode webhook OTP is published next to live-mode setup without disambiguation (minor)

Location: /docs/build/llm-docs/webhooks/validate-test.md

Problem: The page says: "Enter the default OTP 754081 when prompted, while setting up, editing or deleting a webhook in test mode." It sits in a Handy Tips callout on a page that does not, on its own, clarify that live mode has no equivalent bypass.

Consequence: A developer skimming this page mid-integration could reasonably ask whether the same shortcut exists for live mode. There is no in-page statement that it does not.

The fix: Move the test OTP into a clearly bordered "Test Mode only" callout, and explicitly state that live mode requires the real OTP sent to the account owner and has no default.

13. Internet Explorer non-support warning is a fossil (minor)

Location: /docs/build/llm-docs/payments/payment-gateway.md

Problem: The Payment Gateway page carries a Watch Out! callout: "Razorpay Checkout is not supported on Internet Explorer or in Internet Explorer mode in Edge." Internet Explorer was retired by Microsoft in June 2022; the only remaining surface that matters is IE Mode in Edge, which is an enterprise compatibility shim.

Consequence: Leading a Payment Gateway overview with an IE caveat makes the page look out of date and buries the one part that still matters (IE Mode in Edge for enterprise customers). It's a small but visible signal of stale copy on a high-traffic landing page.

The fix: Remove the IE mention entirely and reframe as "Razorpay Checkout is not supported in Internet Explorer mode in Microsoft Edge. All other modern browsers are supported."

What they do well

• Publishing llms.txt at both root and docs level with explicit "Instructions for LLMs" is ahead of most payments-platform peers.
• The public Postman workspace with a forkable collection is a strong agent- and developer-friendly artefact.
• The webhook page is explicit about port restrictions (80/443 only) and IP whitelisting, which prevents a common silent-failure mode.

Top 3 recommendations

1. Fix the empty SDK / Client Libraries blocks across sandbox-setup, server-integration, payment-gateway, and standard.md — these are the on-ramp pages and they currently list zero languages, which also dead-ends the webhook HMAC verification trail.
2. Restore the Standard Checkout build-integration.md page and run a CI link-check across the llm-docs tree so the canonical web integration path can't 404 again.
3. Reconcile the two llms.txt files (matching Last Updated, ISO dates, single source of truth), ship llms-full.txt or stop implying it exists, and add a build-time check that flags future-tense deprecation copy whose date has passed (UPI Collect being the current example).