Finix Documentation (finix-docs-redocly) - Claude Context

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

This is the source repository for Finix's public API documentation, hosted at docs.finix.com. The documentation is built and served using Redocly.

Redocly MCP Server (Published Documentation)

Finix publishes an MCP server that provides AI-assistants access to the published documentation:

To add the Finix Redocly MCP server to Claude Code:

claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http

This MCP server provides semantic search over:

• All published guides at docs.finix.com
• API reference documentation
• Integration guides and best practices

When to use the Redocly MCP server:

• Answering questions about Finix APIs, features, or integration patterns
• Looking up current published documentation
• Verifying how documentation appears to customers

When NOT to use it (use this source repo instead):

• Editing or updating documentation content
• Reviewing unpublished changes
• Working with the OpenAPI specification directly

Repository Purpose

This repository contains the source files for Finix documentation:

• Guides: Markdown files explaining Finix concepts and integration patterns
• API Reference: OpenAPI specification (YAML) for the Finix API
• Assets: Images, diagrams, and static files

Changes merged to main are automatically deployed to docs.finix.com.

Repository Structure

Core Directories

Key Configuration Files

Guide Categories

Located in guides/:

• getting-started/ - Initial setup and quickstart guides
• online-payments/ - Online payment integration
• in-person-payments/ - Terminal and card-present payments
• subscriptions/ - Recurring billing and subscriptions
• payouts/ - Sending money to recipients
• after-the-payment/ - Refunds, disputes, settlements
• platform-payments/ - Marketplace/platform integration
• managing-operations/ - Dashboard, reporting, operations
• industry-considerations/ - Industry-specific guidance
• regional-considerations/ - Region-specific requirements

API Reference Structure

Located in api/:

• index.yaml - Main OpenAPI specification (modular, with $ref)
• index.md - API overview markdown
• components/ - Reusable OpenAPI components
  • schemas/ - Data models (resources, requests, properties)
  • examples/ - Request/response examples (YAML and JSON)
  • requestBodies/ - Reusable request body definitions
  • responses/ - Reusable response definitions
• requests/ - Sample API request files

Key Technologies

• Redocly Reunite - Documentation platform (migrated from Legacy Portal)
• Markdown + Markdoc - Content authoring with custom tags
• OpenAPI 3.x - API specification format
• React/TypeScript - Custom components in @theme/
• npm - Package management

Getting Started

Prerequisites

• Node.js and npm

Local Development

# Clone the repository
git clone https://github.com/finix-payments/finix-docs-redocly.git
cd finix-docs-redocly

# Install dependencies
npm install

# Start development server
npm start

Useful Commands

# Bundle OpenAPI spec into single file
redocly bundle api/index.yaml -o api/bundled.yaml

# Validate the bundled spec
npm run validate

# Check for schema duplication
npm run yq:dupes:mac  # or yq:dupes:win

# Generate JSON examples from YAML
node ./scripts/convertYamlExamplesToJson.js payment_instruments

Content Authoring Guidelines

Markdown Formatting

• Use Markdoc tags ({% tabs %}, {% admonition %}, {% table %}, etc.)
• Add horizontal rules (---) before H2 sections
• Use sequential header levels (H1 → H2 → H3)
• Reference API fields with inline code (`field_name`)

Code Blocks

• Set language and title: ```json {% title="Sample Response" %}
• Use 4-space indentation
• Highlight important lines with // [!code highlight]

File Organization

• Use index.md for folder root pages
• Use absolute paths for images and links
• Organize images into appropriate subfolders (diagrams/, screenshots/, etc.)
• Sort sidebar items by type and alphabetically

SEO

• Set seo.title and seo.description in frontmatter for each page

LLM/MCP Configuration

The redocly.yaml includes an llmstxt configuration that defines which content sections are exposed to the Redocly MCP server at https://docs.finix.com/mcp:

seo:
  llmstxt:
    hide: false
    sections:
      - title: Getting Started
        includeFiles:
          - guides/getting-started/**/*.md
      # ... more sections

This is how the published documentation becomes queryable via the MCP server.

Working with This Repository

Adding/Editing Guides

1. Create or edit .md files in the appropriate guides/ subdirectory
2. Update sidebars.yaml to include new pages
3. Follow the styling guidelines
4. Preview locally with npm start

Updating API Reference

1. Edit files in api/components/schemas/, api/requests/, etc.
2. The modular spec uses $ref references resolved at build time
3. Run npm run validate to check for errors

Adding Images

1. Place in appropriate images/ subfolder
2. Reference with absolute paths: /images/screenshots/my-image.png

Pull Request Process

1. Create a feature branch
2. Make changes and preview locally
3. Open PR against main
4. Docs deploy automatically on merge

Important Notes

• This is a documentation source repo - changes here affect the published docs at docs.finix.com
• Use the Redocly MCP server for querying published documentation programmatically
• Follow existing patterns - check similar pages before creating new content
• Validate OpenAPI changes - run npm run validate before committing API spec changes
• Avoid custom styling - use Redocly's built-in CSS variables when possible

Related Resources

• Published Docs: https://docs.finix.com
• Redocly MCP Server: claude mcp add finix-redocly-mcp https://docs.finix.com/mcp --transport http
• Redocly Documentation: https://redocly.com/docs/realm
• Markdoc Tag Library: https://redocly.com/learn/markdoc/tags/tag-library