​

CLAUDE.md — Cashfree Developer Documentation

​

Role

​

Responsibility

​

Audience

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.

​

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

• 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 <Note>, <Important>, or <Warning> callout as appropriate.

​

Output Expectations

• 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, <Note>, <Warning>, <Tip>, <Steps>, <CodeGroup>, <Tabs>).
• Use Mintlify-native callout components instead of markdown blockquotes for notes, warnings, and tips.

​

Required frontmatter (all fields must be populated — no empty fields)

---
title:
sidebarTitle:
description:
'og:title':
'og:description':
keywords: ['', '', '']
'og:image': ''
---

• 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

• 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)

​

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 for valid fields.
• Always use relative paths from the docs root — no leading slash on paths.

​

MDX Frontmatter (Required on Every Page)

---
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
---

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

​

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.

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

The dashboard shows the following sections:
- Transaction History
- Settlement Status
- Account Balance

​

Code Examples (Highest Priority)

• 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: <API_KEY> not YOUR_API_KEY.
• Show both a success response AND an error/failure response.
• Flag untested examples with a <Warning> callout.

result = payouts.create(amount="YOUR_AMOUNT")

# Requires: cashfree-sdk >= 1.5.0
from cashfree_sdk import Payouts

payouts = Payouts(
    client_id="<CLIENT_ID>",
    client_secret="<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': '...' }

<Tabs>
  <Tab title="Version (2025-01-01)">
    <!-- fenced code block here -->
  </Tab>
</Tabs>

​

API Documentation Standards

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.

• 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

# 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
<Accordion title="Issue: Key not appearing after generation">
  Refresh the browser (Cmd/Ctrl + R) or clear the browser cache.
</Accordion>

## Next steps
- [Integrate the API](/payments/overview)
- [Test in sandbox](/api-reference/overview)

​

Terminology — Standardised Terms

grep -ri "sign in\|signin" docs/payments/
grep -ri " & " docs/payments/ | grep -v "http"

​

Ampersand Rule

• 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

<!-- Expandable Q&A -->
<Accordion title="FAQ Question">Content</Accordion>

<!-- Navigation grids -->
<CardGroup>
  <Card title="Title" href="/path">Description</Card>
</CardGroup>

​

Related Topics Hidden Block

{/* Related topics Section */}
<div class="hidden" data-table-of-contents="bottom">
  <p class="mt-4 font-medium flex items-center gap-2 related-docs-heading">
    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" class="w-4 h-4">
      <path d="M3 4h7a2 2 0 0 1 2 2v13a2 2 0 0-2-2H3z" />
      <path d="M21 4h-7a2 2 0 0 0-2 2v13a2 2 0 0 1 2-2h7z" />
    </svg>
    <span>Related topics</span>
  </p>
  <ul>
    <li><a href="/docs/api-reference/payments/latest/orders/create">Create Order API</a></li>
  </ul>
</div>

• 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

# Start local preview
mint dev

# Check documentation health (must pass before publishing)
node util/checkDocs.mjs

# Clean OpenAPI schema descriptions
node scripts/openapi-rm-desc.js <file>

# 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.

​

AI Knowledge Base Sync (Automated)

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)

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.

• Exclude code blocks, URLs, YAML front matter, and HTML entities from text replacements.
• Log what changed and why.

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: <API_KEY> not YOUR_API_KEY
☐ Success AND failure scenarios shown
☐ Untested code flagged with <Warning>

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

• 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.

​

Reference Files