npm package: @onetreehill/epayments-mcp-server
Description: ePayments MCP Server - AI-powered payment integration assistant for all tech stacks
Author: ePayments
Latest version: 0.1.0

# ePayments MCP Server

AI-powered payment integration assistant for all tech stacks. Integrate ePayments (WeChat Pay, Alipay) into your application using natural language.

## Features

- ✅ **Support All Tech Stacks** - Works with JavaScript, PHP, Java, Python, Ruby, Go, C#, Rust, and more
- ✅ **AI-Powered Code Generation** - AI automatically generates integration code based on comprehensive API documentation
- ✅ **8 Programming Languages** - Detailed code examples in 8 languages
- ✅ **4 Payment Scenarios** - Desktop QR code, Mobile H5, Quick pay, Subscription
- ✅ **Zero Learning Curve** - Just describe what you need in natural language
- ✅ **Production Ready** - Best practices and error handling included

## Installation

### NPM (Recommended)

```bash
npm install -g @epayments/mcp-server
```

### From Source

```bash
git clone https://github.com/epayments/mcp-server.git
cd mcp-server
npm install
npm run build
npm link
```

## Usage

### With Cursor

1. Open Cursor Settings → MCP Servers
2. Add new server configuration:

```json
{
  "mcpServers": {
    "epayments": {
      "command": "epayments-mcp"
    }
  }
}
```

3. Restart Cursor
4. Start using ePayments integration in your project:

```
You: "Help me integrate ePayments WeChat Pay into my Next.js app"

AI: "I'll help you integrate ePayments. Let me get the API documentation..."
[AI automatically calls MCP tools to get documentation and code examples]
[AI generates integration code adapted to your project structure]
```

### With Claude Desktop

1. Edit Claude Desktop config file:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add server configuration:

```json
{
  "mcpServers": {
    "epayments": {
      "command": "epayments-mcp"
    }
  }
}
```

3. Restart Claude Desktop

### With Manus

1. Open Manus MCP Settings
2. Add new server:
   - Name: `epayments`
   - Command: `epayments-mcp`
3. Save and restart Manus

## Available Tools

The MCP server provides 5 tools that AI can use:

### 1. `epayments_get_api_docs`

Get comprehensive API documentation including authentication, parameters, and code examples.

**Parameters:**
- `api` (string): API name - `create_order`, `query_order`, `payment_callback`, or `all`

**Example:**
```
AI: Get ePayments API documentation for creating orders
```

### 2. `epayments_get_payment_scenarios`

Get information about different payment scenarios and their use cases.

**Parameters:**
- `scenario` (string): Scenario name - `desktop_qrcode`, `mobile_h5`, `quick_pay`, `subscription`, or `all`

**Example:**
```
AI: Show me available payment scenarios
```

### 3. `epayments_get_integration_guide`

Get step-by-step integration guide with best practices.

**Parameters:**
- `scenario` (string): Payment scenario to integrate

**Example:**
```
AI: Give me integration guide for desktop QR code payment
```

### 4. `epayments_get_code_example`

Get complete code examples for specific language and scenario.

**Parameters:**
- `language` (string): Programming language - `javascript`, `php`, `java`, `python`, `ruby`, `go`, `csharp`, `rust`
- `scenario` (string): Payment scenario

**Example:**
```
AI: Get PHP code example for quick pay scenario
```

### 5. `epayments_validate_signature`

Validate if signature calculation code is correct.

**Parameters:**
- `code` (string): Signature calculation code
- `language` (string): Programming language

**Example:**
```
AI: Check if my signature code is correct
```

## Real-World Examples

### Example 1: Next.js Integration

```
Developer: "I need to integrate ePayments WeChat Pay into my Next.js app"

AI automatically:
1. Identifies tech stack (Next.js)
2. Gets API documentation
3. Generates Next.js API route code
4. Adds environment variable setup
5. Creates payment callback handler
6. Provides testing instructions
```

### Example 2: Laravel Integration

```
Developer: "Add Alipay payment to my Laravel e-commerce site"

AI automatically:
1. Identifies tech stack (Laravel)
2. Gets API documentation
3. Generates Laravel controller code
4. Adds routes configuration
5. Creates payment callback handler
6. Provides migration files
```

### Example 3: Spring Boot Integration

```
Developer: "Integrate ePayments into my Spring Boot project"

AI automatically:
1. Identifies tech stack (Spring Boot)
2. Gets API documentation
3. Generates @RestController code
4. Creates service layer
5. Adds configuration properties
6. Provides error handling
```

## Supported Tech Stacks

### Officially Supported (High Quality)
- ✅ JavaScript / Node.js (Express)
- ✅ TypeScript / Next.js
- ✅ PHP / Laravel
- ✅ Java / Spring Boot
- ✅ Python / Django / Flask
- ✅ Ruby / Rails
- ✅ Go
- ✅ C# / .NET

### AI-Generated (Good Quality)
- ✅ Rust
- ✅ Elixir
- ✅ Scala
- ✅ Kotlin
- ✅ Swift
- ✅ And any other language!

## Payment Scenarios

### 1. Desktop QR Code Payment
Customer scans QR code with WeChat/Alipay app on their phone.

**Use Cases:**
- E-commerce checkout page
- Point of sale (POS) system
- Self-service kiosk

### 2. Mobile H5 Payment
Redirect to WeChat/Alipay app on mobile device.

**Use Cases:**
- Mobile web checkout
- WeChat mini-program
- Mobile browser payment

### 3. Quick Pay
Customer scans merchant QR code and enters amount.

**Use Cases:**
- Retail stores
- Restaurants
- Service providers

### 4. Subscription Payment
Recurring payment for subscriptions.

**Use Cases:**
- SaaS subscriptions
- Membership fees
- Recurring services

## How It Works

1. **You describe what you need** in natural language
2. **AI calls MCP tools** to get ePayments API documentation
3. **AI analyzes your project** structure and tech stack
4. **AI generates integration code** adapted to your project
5. **You review and use** the generated code

## Benefits

### For Developers
- ✅ No need to read lengthy documentation
- ✅ Code automatically adapted to your tech stack
- ✅ Best practices included
- ✅ Error handling built-in
- ✅ Production-ready code

### For Teams
- ✅ Consistent code quality
- ✅ Faster integration (5-10 minutes vs 1-3 days)
- ✅ Reduced learning curve
- ✅ Easier maintenance

### For Businesses
- ✅ Faster time to market
- ✅ Lower development cost
- ✅ Support for any tech stack
- ✅ Reduced technical debt

## Requirements

- Node.js >= 18.0.0
- ePayments Merchant ID and Key (get from [ePayments](https://epayments.co.nz))
- AI tool that supports MCP (Cursor, Claude Desktop, Manus, etc.)

## Environment Variables

```bash
# .env
EPAYMENTS_MERCHANT_ID=MCH_123456
EPAYMENTS_KEY=your_merchant_key
EPAYMENTS_API_URL=https://api-dev.epayments.co.nz  # Use production URL in production
```

## API Endpoints

### Production
```
https://api.epayments.co.nz
```

### Sandbox (Testing)
```
https://api-dev.epayments.co.nz
```

## Authentication

All ePayments APIs use HMAC-SHA256 signature authentication:

1. Sort all request parameters alphabetically
2. Convert to JSON string
3. Calculate HMAC-SHA256 signature using Merchant Key
4. Add signature to request header: `X-Signature`
5. Add Merchant ID to request header: `X-Merchant-Id`

The MCP server provides detailed code examples for signature generation in all supported languages.

## Troubleshooting

### MCP Server Not Found

Make sure the server is installed globally:
```bash
npm install -g @epayments/mcp-server
```

Or use full path in MCP config:
```json
{
  "command": "/path/to/node_modules/.bin/epayments-mcp"
}
```

### Signature Verification Failed

Use the `epayments_validate_signature` tool to check your signature code:
```
AI: Check if my signature calculation is correct
```

### Payment Callback Not Received

Make sure:
- Callback URL is publicly accessible
- HTTPS certificate is valid
- Callback endpoint returns 200 status with `{code: 0}` response
- Firewall allows ePayments servers

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT

## Support

- Documentation: [https://epayments.co.nz/docs](https://epayments.co.nz/docs)
- Email: support@epayments.co.nz
- GitHub Issues: [https://github.com/epayments/mcp-server/issues](https://github.com/epayments/mcp-server/issues)

## About ePayments

ePayments is a leading payment gateway provider in New Zealand, offering WeChat Pay and Alipay integration for businesses of all sizes.

---

Made with ❤️ by ePayments Team