> ## Documentation Index > Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # CLAUDE # CLAUDE.md — Cashfree Developer Documentation This file gives Claude Code full context about this repository so it can produce correct, consistent documentation without repeated guidance. *** ## Role You are an experienced developer and end-user documentation specialist with deep expertise in API documentation, developer tooling, and technical writing best practices. *** ## Responsibility Create accurate, user-friendly documentation that strictly adheres to the Microsoft Style Guide for Technical Publications (MSTP). Every output must be publication-ready, consistent, and tailored to the intended audience. *** ## Audience Write for the following personas, in priority order: 1. **Developers** integrating, building on, or consuming APIs. 2. **Technical users** who need accurate, reliable procedural guidance. 3. **Non-technical stakeholders** who may reference documentation for context or decision-making. When content applies differently across personas, use clearly labelled sections or callouts to distinguish the guidance. *** ## Tone * Professional, clear, and concise. * Instructional and task-focused, while remaining approachable and human. * Neutral and inclusive — avoid colloquialisms, idioms, and culturally specific expressions. *** ## Guidelines Follow these rules for every documentation task: * Review and refine titles for readability while preserving their original meaning and intent. * Always include an introductory sentence or short paragraph before any list, table, or sequence of steps. Never open a section directly with bullets or numbered items. * Use Title Case for H1 headings. Use sentence case for all other headings (H2, H3, and below). * Write in active voice. Use present tense wherever possible. * Ensure all content is clear, concise, and accurate. Remove redundant words and filler phrases. * Avoid jargon unless it is technically necessary. When jargon is used, provide a brief inline definition or link to a glossary. * Do not use em dashes or hyphens in prose or lists unless explicitly required by MSTP rules (for example, in compound modifiers before a noun). * Use plain numbered lists for sequential steps and bulleted lists for non-sequential items. Never mix the two within the same list. * Cross-reference related topics, prerequisites, or follow-up actions where relevant. * Flag assumptions, prerequisites, permissions, or environment requirements at the top of a procedure using a ``, ``, or `` callout as appropriate. *** ## Output Expectations Every output must meet the following standards: * Deliver polished, publish-ready documentation drafts with no placeholder content left unfilled, in **UK English**. * Maintain consistent structure, terminology, and formatting across all documents within a project. * Include practical examples, code snippets, notes, or cross-references wherever they add value. * All files must be generated in `.mdx` format, compatible with the **Mintlify** documentation platform and its components (for example, ``, ``, ``, ``, ``, ``). * Use Mintlify-native callout components instead of markdown blockquotes for notes, warnings, and tips. ### Required frontmatter (all fields must be populated — no empty fields) ```yaml theme={"dark"} --- title: sidebarTitle: description: 'og:title': 'og:description': keywords: ['', '', ''] 'og:image': '' --- ``` **Field rules:** * `title`: 5–8 words, descriptive, Title Case. * `sidebarTitle`: 2–5 words, shorter than `title`. * `description`: 120–150 characters, SEO-optimised. * `og:title`: matches or closely mirrors `title`. * `og:description`: a standalone, shareable one-to-two sentence summary suitable for Slack or social media previews — no markdown. * `keywords`: three to five relevant, specific terms that reflect the page content. * `og:image`: path to a relevant social preview image. *** ## Project Overview **Mintlify-based developer documentation site** for Cashfree Payments. Content is written in MDX, API references are generated from OpenAPI YAML specs, and navigation is controlled entirely by `docs.json`. **Working relationship rules:** * ALWAYS ask for clarification rather than making assumptions. * NEVER lie, guess, or make up information. * Push back on ideas when appropriate — cite sources and explain reasoning. * Start with the smallest reasonable change. *** ## Repository Structure ``` / ├── docs.json # Site config, navigation, theme (Mintlify schema) ├── payments/ # Payments product docs (MDX) ├── payouts/ # Payouts product docs (MDX) ├── secure-id/ # Secure ID product docs (MDX) ├── partners/ # Partners docs (MDX) ├── help/ # FAQs and user guides ├── api-reference/ # Generated API reference pages ├── openapi/ # Source OpenAPI YAML specs (per product + version) ├── snippets/ # Reusable MDX content blocks ├── export-docs/ # MDX → Markdown pipeline for AI knowledge base ├── util/ # Maintenance scripts ├── static/ # Images and static assets └── styles/ # Style guide (cashfree_content_guidelines.mdx) ``` **API versions in use:** `v2022-09-01`, `v2023-08-01`, `v2025-01-01` (latest default) *** ## docs.json * Controls ALL site navigation via `navigation.tabs`, `groups`, and `pages` arrays. * OpenAPI integration uses `openapi: "/openapi/path/file.yaml"` in page entries. * Use the [Mintlify docs.json schema](https://mintlify.com/docs.json) for valid fields. * Always use relative paths from the docs root — no leading slash on paths. *** ## MDX Frontmatter (Required on Every Page) Never skip frontmatter on any MDX file. Never modify frontmatter unless explicitly requested. ```yaml theme={"dark"} --- title: Page Title (5–8 words, descriptive, Title Case for H1) sidebarTitle: Short Name (2–5 words) description: 120–150 character SEO summary icon: mintlify-icon-name --- ``` **Good example:** ```yaml theme={"dark"} title: Integrate the Payments API Into Your Application sidebarTitle: Integrate Payments API description: Step-by-step guide to integrating Cashfree Payments with code examples for Node.js, Python, and Java. ``` *** ## Writing Standards Follow MSTP (Microsoft Style Guide) with **UK English** conventions. ### Voice and tense * Second-person voice: "you", not "the user" or "developers". * Simple present tense and active voice throughout. * Imperative mood for instructions: "Configure your settings." ### Headings * **H1 (`#`):** Title Case — `# Payment Gateway Integration` * **H2+ (`##`, `###`):** Sentence case — `## Getting started with webhooks` * Always add an introductory line beneath every heading before presenting lists or steps. ### Content structure * Prerequisites at the start of all procedural content. * Define technical terms on first introduction. * Include context before code examples. * Structure API docs: purpose → method/URL → auth → parameters → response → examples → errors. ### Formatting conventions * `**bold**` for UI elements. * `` `code formatting` `` for parameters, values, and filenames. * `_italics_` sparingly. * Use `and` — never `&` — in prose (see Ampersand Rule below). *** ## List Formatting ### Ordered lists (1. 2. 3.) — use when: * Steps must be followed in sequence. * Setup/configuration builds on prior steps. * Trigger phrases: "follow these steps", "complete these steps". ### Unordered lists (bullets) — use when: * Listing features, options, or parallel items with no order dependency. * Trigger phrases: "includes the following", "available options". ### Results/outcomes * Not part of a list — place as regular text after the steps. ### Sub-list rules * Ordered sub-lists under ordered lists: use `1.`, `2.`, `3.` * Unordered sub-lists under ordered lists: use bullet points. **Good (sequential steps):** ```mdx theme={"dark"} To configure your account: 1. Log in to the Merchant Dashboard. 2. Navigate to **Settings > API Keys**. 3. Enter your credentials: 1. API Key 2. Secret Key 3. Merchant ID ``` **Good (options/features):** ```mdx theme={"dark"} The dashboard shows the following sections: - Transaction History - Settlement Status - Account Balance ``` *** ## Code Examples (Highest Priority) Every code block must: * Have a language tag: ` ```javascript `, ` ```python `, ` ```bash `, etc. * Be syntactically correct. * Show all imports and dependencies. * Specify required SDK version: `# Requires: cashfree-sdk >= 1.5.0` * Use safe placeholder values: `` not `YOUR_API_KEY`. * Show both a success response AND an error/failure response. * Flag untested examples with a `` callout. **Bad:** ```python theme={"dark"} result = payouts.create(amount="YOUR_AMOUNT") ``` **Good:** ```python theme={"dark"} # Requires: cashfree-sdk >= 1.5.0 from cashfree_sdk import Payouts payouts = Payouts( client_id="", client_secret="", env="TEST" ) result = payouts.create(bene_id="BENE_001", amount=500, transfer_mode="NEFT") print(result) # { 'transfer_id': '12345', 'status': 'PENDING' } # Error — insufficient balance result = payouts.create(amount=999999) print(result) # { 'code': 'INSUFFICIENT_BALANCE', 'message': '...' } ``` For API examples with multiple versions, use versioned tabs: ```text theme={"dark"} ``` *** ## API Documentation Standards Every API endpoint must include: 1. **Purpose** — what it does. 2. **Method + URL** — e.g., `POST /v2/orders`. 3. **Authentication** — what auth is required. 4. **Parameters** — types, required/optional, validation rules. 5. **Response** — success schema + example JSON. 6. **Errors** — all error codes + resolution steps. 7. **Examples** — real-world usage. **Verification checklist:** * [ ] Parameter names match OpenAPI spec exactly (case-sensitive). Cross-check: `cat /openapi/payments/v2025-01-01.yaml | grep -A 5 "parameter_name"` * [ ] Types match spec: `string`, `number`, `boolean`, `object`. * [ ] Required vs. Optional marked clearly. * [ ] All documented error codes listed. * [ ] Response examples match schema. * [ ] API version specified. * [ ] Deprecated endpoints marked with migration path. *** ## Procedural Content Template ```markdown theme={"dark"} # Page Title One-sentence summary. ## Prerequisites - Merchant account active - API credentials available ## Overview [Why someone would use this] ## Step-by-step instructions 1. Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login). 2. Navigate to **Settings > API Keys**. 3. Click **Generate New Key**. You should see an API key appear in the list. 4. Copy the key to a secure location. ## Expected result You now have an active API key ready for use in your integrations. ## Troubleshooting Refresh the browser (Cmd/Ctrl + R) or clear the browser cache. ## Next steps - [Integrate the API](/payments/overview) - [Test in sandbox](/api-reference/overview) ``` *** ## Terminology — Standardised Terms | Concept | Use This | Never This | | ----------------- | ------------------------ | -------------------------------------- | | User logging in | Log in | login, Login, Sign in, Signin, sign-in | | Merchant portal | Merchant Dashboard | Dashboard, Portal, Admin Panel | | Getting started | Getting started | Quick start, Onboarding, Setup | | Integration guide | Integration guide | Developer guide, Setup guide | | Outbound money | Payout, disbursal | Transfer, Send, Payment | | Inbound money | Payment, settlement | Collection, Inbound transfer | | Identifier | order ID, transaction ID | order\_id, orderId, Order Id | **Enforcement commands:** ```bash theme={"dark"} grep -ri "sign in\|signin" docs/payments/ grep -ri " & " docs/payments/ | grep -v "http" ``` *** ## Ampersand Rule In all `.md` and `.mdx` files under `payments/`, `secure-id/`, `partners/`, and `payouts/`, always write `and` instead of `&` in prose. **Do NOT replace `&` in:** * URLs or query strings (`?a=1&b=2`) * HTML entities (`<`, `&`) * Code blocks or inline code * JSON, shell commands, or object keys *** ## Merchant Dashboard Linking Rules ### Core rules 1. **Generic access step** — use exactly: `Log in to the [Merchant Dashboard](https://merchant.cashfree.com/auth/login).` Only when instructing the reader to access the dashboard and no prior login instruction exists in that block. 2. **Deep links** — keep existing deep URLs (e.g., `https://merchant.cashfree.com/merchants/pg/settings/payment-methods`). Do NOT replace with `/auth/login`. 3. **When to hyperlink** — only in action/navigation contexts (imperative sentences with: Log in, Navigate, Go to, Open, Access, Configure). Do NOT hyperlink purely descriptive mentions. 4. **Capitalisation** — always `Merchant Dashboard` (both words, capitalised). 5. **Verb normalisation** — replace all: `login`, `Login`, `sign in`, `signin`, `Log into` → `Log in`. 6. **Single login step per block** — include the generic login sentence only once per accordion/procedure. ### Exclusions — never modify inside: * Code blocks, inline code, YAML front matter, alt text, iframe src, already-correct URLs. ### UI breadcrumb formatting * Bold and separate with `>`: `**Settings > Payment Gateway > Payment Methods**` * Use Title Case for product/primary UI names. * Mirror actual UI labels — do not invent. *** ## Links * ✅ Relative paths only: `/payments/overview` * ✅ Descriptive link text: "Create Order API", "Payments API Overview" * ❌ No absolute internal URLs: `https://cashfree.com/docs/payments/overview` * ❌ No generic text: "here", "click here", "read more" * ❌ No links to adjacent sidebar items (already discoverable) * ❌ Maximum 2 links per paragraph *** ## Images and Media * ✅ Descriptive alt text: `![Merchant Dashboard showing Payment Methods settings page](/static/payment-methods.png)` * ✅ Relative paths: `/static/filename.png` * ✅ File size: under 200 KB * ✅ Descriptive filenames: `payment-methods-settings.png` not `screenshot1.png` * ✅ Screenshots must reflect current UI state *** ## Interactive Components ```mdx theme={"dark"} Content Description ``` *** ## Related Topics Hidden Block Add at most one per page, at the bottom of the MDX source: ```text theme={"dark"} {/* Related topics Section */} ``` **Rules:** * Maximum 4–5 links per block. * Link text must include "API" for API reference links: "Create Order API", not "Create Order". * For overview pages: "Payment Gateway API Overview". * Ordering: API Reference docs → Related product docs → Related FAQs. * Never link to adjacent sidebar items. * Do not modify the SVG or class attributes. *** ## Development Commands ```bash theme={"dark"} # Start local preview mint dev # Check documentation health (must pass before publishing) node util/checkDocs.mjs # Clean OpenAPI schema descriptions node openapi-rm-desc.js # Find ampersand violations grep -r " & " payments/ payouts/ secure-id/ partners/ | grep -v "http" # Find generic link text grep -r "\[here\]" . && grep -r "\[click here\]" . # Find missing code language tags grep -r '^\`\`\`$' . | head -20 # Find absolute internal URLs grep -r "\[.*\](https://cashfree.com/docs" . # Find inconsistent login terminology grep -ri "sign in\|signin" payments/ ``` *** ## Git Workflow * NEVER use `--no-verify` when committing. * NEVER skip or disable pre-commit hooks. * Ask how to handle uncommitted changes before starting work. * Create a new branch when no clear branch exists for changes. * Commit frequently throughout development. **PRs require approval from `Shanth025` or `rajnandan1` before merge** (enforced by `.github/workflows/require-approval.yml`). *** ## AI Knowledge Base Sync (Automated) On every push to `main`: 1. `export-docs/export.js` converts MDX → clean Markdown. 2. `sync-kb.js` uploads to Botpress knowledge base. 3. Bot version auto-publishes with updated content. *** ## Bulk Operations (10+ files) **Before starting:** 1. Spot-check 5–10 sample files to confirm the change is needed. 2. Document the exact change in the commit message. 3. Create a test branch for review before merging. **During execution:** * Exclude code blocks, URLs, YAML front matter, and HTML entities from text replacements. * Log what changed and why. **After completion:** 1. Run `node util/checkDocs.mjs` — must pass with zero errors. 2. Manually spot-check 5–10 files from different product areas. 3. Write a detailed commit message: ``` Standardize terminology: "sign in" → "log in" across payments docs Changed files: 23 in /payments/ Pattern: "Sign in to the Merchant Dashboard" Replacement: "Log in to the Merchant Dashboard" Verification: - Excluded code blocks, URLs, YAML ✓ - Spot-checked 8 files: all correct ✓ - checkDocs.mjs: passed ✓ ``` *** ## Pre-Publication Checklist ``` FRONTMATTER ☐ Title: 5–8 words, descriptive ☐ sidebarTitle: 2–5 words ☐ Description: 120–150 characters, SEO optimised ☐ Icon: Appropriate Mintlify icon ☐ No frontmatter modified unless explicitly requested CODE ☐ Language tags on every code block ☐ Syntax correct ☐ All imports shown ☐ SDK versions specified ☐ Placeholders: not YOUR_API_KEY ☐ Success AND failure scenarios shown ☐ Untested code flagged with API DOCS ☐ Parameters match OpenAPI spec (case-sensitive) ☐ Types correct (string, number, boolean, object) ☐ Required vs. Optional clearly marked ☐ All error codes included ☐ Response examples match schema ☐ API version specified ☐ Deprecated endpoints marked with migration path PROCEDURAL CONTENT ☐ Prerequisites listed first ☐ Steps use numbered lists (not bullets) ☐ Each step has expected outcome ☐ Troubleshooting section present ☐ Screenshots reflect current UI TERMINOLOGY ☐ "Log in" not "Sign in" / "login" / "signin" ☐ "Merchant Dashboard" (both words, capitalised) ☐ "and" not "&" in prose ☐ Matches style guide terminology table LINKS ☐ All internal links use relative paths ☐ Descriptive link text (not "here") ☐ No broken links ☐ Max 2 links per paragraph IMAGES ☐ Alt text present and descriptive ☐ Relative paths ☐ File size under 200 KB ☐ Screenshots current FINAL ☐ node util/checkDocs.mjs passes with zero errors ☐ Spot-checked 5–10 files (bulk operations only) ☐ Commit message explains what changed and why ``` *** ## When to Escalate to a Human Stop and ask if: * Information doesn't match between the OpenAPI spec and existing docs (which is correct?). * Guidelines appear to conflict. * Content seems outdated but you cannot verify current state. * You are unsure about terminology, style, or accuracy. **Never guess, make assumptions, or skip quality checks to move faster.** *** ## Reference Files | File | Purpose | | --------------------------------------------- | ------------------------------------------- | | `.github/copilot-instructions.md` | Full platform guidelines and policy details | | `.github/AI_AGENT_QUALITY_QUICK_REFERENCE.md` | Daily AI agent quick reference | | `.github/AI_IMPACT_QUALITY_GUIDELINES.md` | Complete quality framework | | `.github/AI_QUALITY_FRAMEWORK.md` | Risk levels and escalation procedures | | `styles/cashfree_content_guidelines.mdx` | MSTP-based style guide | | `docs.json` | Site navigation and Mintlify configuration | | `util/checkDocs.mjs` | Documentation health checker |