> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitpayapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Plugin

> Claude Code plugin for building HitPay payment integrations: an MCP server with 28 live API tools, 5 auto-triggered skills, and 4 slash commands. Covers 50+ payment methods across Southeast Asia.

The HitPay Claude Code Plugin connects Claude Code to the HitPay payment API. It ships an MCP server with 28 tools, 5 auto-triggered skills, and 4 slash commands. You describe the integration you need, and Claude generates the code, calling the live API where that helps (looking up payment methods, creating test payment requests, verifying results).

## Plugin vs. Agent Skills

HitPay offers two AI integration approaches. Choose the one that fits your workflow.

| Feature                    | Claude Code Plugin                                   | [Agent Skills](/apis/guide/ai-skills)  |
| -------------------------- | ---------------------------------------------------- | -------------------------------------- |
| **Installation**           | `/plugin marketplace add hit-pay/claude-code-plugin` | `npx skills add hit-pay/agent-skills`  |
| **Live API access**        | 28 MCP tools (read + safe create)                    | None, code generation only             |
| **Auto-triggered skills**  | 5 (payment, webhook, methods, UI, QR)                | 2 (payment, webhook)                   |
| **Slash commands**         | 4 (`/hitpay:init`, `/hitpay:methods`, etc.)          | None                                   |
| **AI assistants**          | Claude Code only                                     | Claude Code, Cursor, Copilot, Windsurf |
| **Sandbox support**        | Built-in (default environment)                       | Via env vars                           |
| **Destructive operations** | Excluded by design                                   | N/A                                    |

<Info>
  The plugin only works in Claude Code. If you use **Cursor, GitHub Copilot, or Windsurf**, use [Agent Skills](/apis/guide/ai-skills) instead.
</Info>

<Info>
  To query your business data (sales, payouts, transactions) from an AI assistant without building an integration, use the hosted [HitPay MCP Server](/apis/guide/mcp-server) instead. It authenticates with your HitPay login rather than an API key.
</Info>

## What's Included

<CardGroup cols={3}>
  <Card title="MCP Server" icon="server">
    28 live API tools: create payment requests, list charges, manage customers, generate QR codes, and more. All operations are read or safe-create.
  </Card>

  <Card title="5 Auto-Triggered Skills" icon="wand-magic-sparkles">
    Claude activates the relevant skill based on your prompt: payment integration, webhook handling, method lookup, embedded UI, or QR checkout.
  </Card>

  <Card title="4 Slash Commands" icon="terminal">
    Scaffolding commands for common workflows: `/hitpay:init`, `/hitpay:methods`, `/hitpay:webhook-test`, `/hitpay:qr-checkout`.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the plugin">
    Inside Claude Code, add the marketplace and install the plugin:

    ```
    /plugin marketplace add hit-pay/claude-code-plugin
    /plugin install hitpay@hitpay-plugins
    ```

    Or clone locally for development:

    ```bash theme={"system"}
    git clone https://github.com/hit-pay/claude-code-plugin.git hitpay-plugin
    claude --plugin-dir ./hitpay-plugin
    ```
  </Step>

  <Step title="Set environment variables">
    Add your HitPay API credentials:

    ```bash theme={"system"}
    export HITPAY_API_KEY=your_api_key_here
    export HITPAY_SALT=your_webhook_salt_here
    export HITPAY_ENV=sandbox
    ```

    Get your API key from **Dashboard → Settings → Payment Gateway → API Keys**.
    Get your webhook salt from **Dashboard → Settings → Developers → Webhook Endpoints**.
  </Step>

  <Step title="Start building">
    Open Claude Code and describe what you want:

    ```
    "Add PayNow and GrabPay to my Next.js checkout"
    ```

    Claude uses the live API and the relevant skill to generate the integration code.
  </Step>
</Steps>

<Warning>
  Always start with `HITPAY_ENV=sandbox`. Switch to `HITPAY_ENV=production` only when you are ready to accept real payments. The plugin defaults to sandbox mode.
</Warning>

## MCP Server: 28 API Tools

The plugin's MCP server gives Claude live access to the HitPay API. All operations are either read-only or safe-create; no destructive operations are exposed.

| Category               | Tools | Operations                                                       |
| ---------------------- | ----- | ---------------------------------------------------------------- |
| **Payment Requests**   | 5     | Create, get, list, update, delete (pending only)                 |
| **Charges**            | 2     | List charges, get charge detail                                  |
| **Account & Balances** | 2     | Get balances, get account status                                 |
| **Customers**          | 3     | Create, list, get                                                |
| **Invoices**           | 2     | Create, list                                                     |
| **QR Codes**           | 4     | Get supported methods, create embedded QR, create/list static QR |
| **Subscriptions**      | 4     | List plans, create/cancel billing, charge saved card             |
| **Webhooks**           | 3     | Create/delete webhook events, get remitter                       |
| **Analytics**          | 1     | Get sales summary                                                |
| **Products**           | 2     | List products, get account info                                  |

<Note>
  Refunds, transfers, and bulk deletions are intentionally excluded, so Claude cannot trigger irreversible financial operations even with a production API key.
</Note>

## Auto-Triggered Skills

Skills activate automatically based on what you ask Claude. No manual invocation needed.

| Skill                   | Triggers When You Say                                               | What It Does                                                                                 |
| ----------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **payment-integration** | "Add HitPay", "payment checkout", "accept payments"                 | Generates API routes, redirect/QR/selector checkout flows, auth headers, and test card setup |
| **webhook-handler**     | "webhook signature", "verify webhook", "payment notification"       | Generates HMAC-SHA256 verification (mandatory), event routing, idempotency handling          |
| **payment-methods**     | "methods in Malaysia", "supported methods", "which payment methods" | Returns country-to-method mapping with exact API codes, currencies, and availability         |
| **drop-in-ui**          | "embed payment form", "HitPay.js", "checkout popup"                 | Generates HitPay.js script integration, init options, Next.js component, event handling      |
| **qr-checkout**         | "QR checkout page", "QR payment page", "show QR code"               | Generates a branded HTML page with scannable QR, countdown timer, offline-capable            |

## Slash Commands

| Command                | Description                                                           | Example                                   |
| ---------------------- | --------------------------------------------------------------------- | ----------------------------------------- |
| `/hitpay:init`         | Scaffold a complete HitPay integration for your framework and markets | `/hitpay:init nextjs sg,my`               |
| `/hitpay:methods`      | Look up available payment methods by country                          | `/hitpay:methods ph`                      |
| `/hitpay:webhook-test` | Generate a test webhook payload and curl command                      | `/hitpay:webhook-test charge.created`     |
| `/hitpay:qr-checkout`  | Generate a QR payment page for specific methods                       | `/hitpay:qr-checkout 100 sgd paynow,qris` |

## Supported Payment Methods

The plugin covers 50+ payment methods across 8 markets with automatic cross-border support.

| Market           | Currency | Payment Methods                                          |
| ---------------- | -------- | -------------------------------------------------------- |
| **Singapore**    | SGD      | PayNow, GrabPay, ShopeePay, Cards, Apple Pay, Google Pay |
| **Malaysia**     | MYR      | FPX, Touch 'n Go, DuitNow, GrabPay, ShopeePay, Boost     |
| **Philippines**  | PHP      | GCash, Maya, QR Ph, ShopeePay                            |
| **Thailand**     | THB      | PromptPay, TrueMoney                                     |
| **Indonesia**    | IDR      | QRIS, OVO, DANA                                          |
| **Vietnam**      | VND      | VietQR, ZaloPay                                          |
| **India**        | INR→SGD  | UPI (with automatic FX conversion)                       |
| **Australia**    | AUD      | PayTo, Cards                                             |
| **Cross-border** | Auto FX  | 9 borderless QR methods with real-time exchange rates    |

## Usage Examples

<Tabs>
  <Tab title="Add Payments">
    **Prompt:** "Add PayNow and card payments to my Next.js app"

    Claude will:

    1. Create an API route at `app/api/payments/create/route.ts`
    2. Generate a checkout component with redirect flow
    3. Set up webhook handler with HMAC-SHA256 verification
    4. Add environment variable configuration
  </Tab>

  <Tab title="Webhook Verification">
    **Prompt:** "Set up HitPay webhook handling with signature verification"

    Claude will:

    1. Generate a webhook endpoint with HMAC-SHA256 signature validation
    2. Add event type routing (payment completed, refund issued, etc.)
    3. Include idempotency checks to prevent duplicate processing
    4. Add error handling and logging
  </Tab>

  <Tab title="QR Checkout">
    **Prompt:** "Create a PayNow QR checkout page for SGD 50"

    Claude will:

    1. Call the live API to create an embedded QR payment request
    2. Generate a branded HTML page with the QR code
    3. Add a countdown timer for QR expiration
    4. Include the checkout URL as a fallback link
  </Tab>

  <Tab title="Method Lookup">
    **Prompt:** "What payment methods are available in the Philippines?"

    Claude will:

    1. Query the live API for available methods in PH
    2. Return GCash, Maya, QR Ph, ShopeePay with exact API codes
    3. Show currency (PHP) and any cross-border options
  </Tab>
</Tabs>

## Prerequisites

Before installing the plugin, ensure you have:

1. **HitPay Account**: [create an account](https://dashboard.hit-pay.com) or use the [sandbox environment](https://dashboard.sandbox.hit-pay.com)
2. **API Key**: found in **Settings → Payment Gateway → API Keys**
3. **Webhook Salt**: found in **Settings → Developers → Webhook Endpoints**
4. **Claude Code**: the plugin requires [Claude Code](https://claude.ai/claude-code) (Anthropic's CLI)

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What is the HitPay Claude Code Plugin?">
    The HitPay Claude Code Plugin connects Claude Code to HitPay's live payment API. It includes an MCP server with 28 API tools, 5 auto-triggered skills for common integration tasks, and 4 slash commands for scaffolding. You describe what you want in natural language, and Claude generates the payment integration code.
  </Accordion>

  <Accordion title="How is the Claude Code Plugin different from HitPay Agent Skills?">
    The Claude Code Plugin provides **live API access** through an MCP server: Claude can create real payment requests, query charges, and check balances. Agent Skills only provide code generation templates without API connectivity. The plugin also includes slash commands and more auto-triggered skills. However, Agent Skills work with Cursor, Copilot, and Windsurf, while the plugin only works in Claude Code.
  </Accordion>

  <Accordion title="Is it safe to use with production API keys?">
    Yes. The plugin excludes all destructive operations: no refunds, no transfers, no bulk deletions. All 28 MCP tools are either read-only or safe-create operations, so Claude cannot trigger irreversible financial actions through the plugin.
  </Accordion>

  <Accordion title="Does the plugin support sandbox testing?">
    Yes. The plugin defaults to sandbox mode (`HITPAY_ENV=sandbox`). All API calls go to `api.sandbox.hit-pay.com` until you explicitly set `HITPAY_ENV=production`. Use test card `4242 4242 4242 4242` with any expiry and CVC in sandbox.
  </Accordion>

  <Accordion title="What payment methods are supported?">
    The plugin supports 50+ payment methods across Singapore, Malaysia, Philippines, Thailand, Indonesia, Vietnam, India, and Australia. This includes PayNow, FPX, QRIS, GrabPay, GCash, PromptPay, UPI, and 9 cross-border QR methods with automatic FX conversion.
  </Accordion>

  <Accordion title="Can I use this with Cursor or GitHub Copilot?">
    No. The Claude Code Plugin requires Claude Code (Anthropic's CLI) because it uses the MCP server protocol and Claude Code's plugin system. For Cursor, GitHub Copilot, or Windsurf, use [HitPay Agent Skills](/apis/guide/ai-skills) instead.
  </Accordion>

  <Accordion title="How do I switch from sandbox to production?">
    Change your environment variable from `HITPAY_ENV=sandbox` to `HITPAY_ENV=production` and update `HITPAY_API_KEY` to your production API key. Your production key is found in your live HitPay Dashboard under **Settings → Payment Gateway → API Keys**.
  </Accordion>

  <Accordion title="What frameworks does the plugin support?">
    The plugin is optimized for **Next.js** (App Router) but works with any Node.js/TypeScript framework. Claude adapts the generated code for Express, Fastify, Remix, SvelteKit, or vanilla Node.js based on your project structure.
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/hit-pay/claude-code-plugin">
    View source, report issues, and contribute
  </Card>

  <Card title="API Reference" icon="code" href="/apis/payment-request/create-request">
    Full API documentation
  </Card>

  <Card title="Webhook Events" icon="bell" href="/apis/guide/events">
    Handle payment notifications
  </Card>

  <Card title="Sandbox Guide" icon="flask" href="/apis/guide/sandbox">
    Test your integration
  </Card>

  <Card title="Agent Skills" icon="wand-magic-sparkles" href="/apis/guide/ai-skills">
    Alternative for Cursor, Copilot, and Windsurf
  </Card>

  <Card title="Payment Methods" icon="credit-card" href="/apis/guide/payment-methods-reference">
    Full payment method reference
  </Card>
</CardGroup>

## Feedback

Have suggestions or found an issue? [Open an issue](https://github.com/hit-pay/claude-code-plugin/issues) on GitHub.