mcsacca/2pay-mcp-server

2Pay MCP Server

A Model Context Protocol (MCP) server for the 2Checkout/Verifone 2Pay.js payment API. This server enables AI assistants like Claude to interact with payment processing, subscription management, and order operations through natural language.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Available Tools
• Resources & Prompts
• Usage Examples
• Architecture
• Environment Variables
• Security
• Troubleshooting
• API Documentation
• Contributing
• License

Features

• Order Management: Place orders with 2Pay.js tokens, retrieve order details, search orders, process refunds
• Subscription Management: Full lifecycle management including renewals, upgrades, payment updates
• Customer Management: Create, update, and manage customer records and their subscriptions
• Product Catalog: Query and manage products, pricing configurations, and price options
• Promotions: Create discounts, generate coupon codes, manage promotional campaigns

Prerequisites

• Node.js 18 or higher
• 2Checkout/Verifone merchant account
• API credentials (merchant code and secret key)
• For production: PCI DSS compliance awareness

Installation

Option 1: npm (Recommended)

npm install -g @mcsacca/2pay-mcp-server

Option 2: Using npx (No Installation)

You can run directly with npx - see Configuration below.

Option 3: From Source

git clone https://github.com/mcsacca/2pay-mcp-server.git
cd 2pay-mcp-server
npm install
npm run build

Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (Recommended)

{
  "mcpServers": {
    "2pay": {
      "command": "npx",
      "args": ["-y", "@mcsacca/2pay-mcp-server"],
      "env": {
        "TWOCHECKOUT_MERCHANT_CODE": "your_merchant_code",
        "TWOCHECKOUT_SECRET_KEY": "your_secret_key",
        "TWOCHECKOUT_SANDBOX": "true"
      }
    }
  }
}

Using Global Installation

{
  "mcpServers": {
    "2pay": {
      "command": "2pay-mcp-server",
      "env": {
        "TWOCHECKOUT_MERCHANT_CODE": "your_merchant_code",
        "TWOCHECKOUT_SECRET_KEY": "your_secret_key",
        "TWOCHECKOUT_SANDBOX": "true"
      }
    }
  }
}

Using Local Build

{
  "mcpServers": {
    "2pay": {
      "command": "node",
      "args": ["/path/to/2pay-mcp-server/dist/index.js"],
      "env": {
        "TWOCHECKOUT_MERCHANT_CODE": "your_merchant_code",
        "TWOCHECKOUT_SECRET_KEY": "your_secret_key",
        "TWOCHECKOUT_SANDBOX": "true"
      }
    }
  }
}

Available Tools

Order Tools (7)

Subscription Tools (22)

Customer Tools (6)

Product Tools (7)

Promotion Tools (7)

Usage Tools (5)

Lead Tools (5)

Campaign Tools (8)

Shipping Tools (3)

SKU Tools (4)

Account Tools (5)

SSO Tools (4)

Internationalization Tools (5)

Resources & Prompts

Resources

• 2pay://config - Current configuration status and API endpoints
• 2pay://error-codes - Common error codes and their meanings

Prompts

• create-order - Guided workflow for creating an order with a 2Pay.js token
• manage-subscription - Guided workflow for subscription management operations
• troubleshoot-payment - Diagnose and resolve payment issues

Usage Examples

Place an Order with 2Pay.js Token

{
  "token": "190f2d9c-0bbc-4ad0-a902-770adb8e7f90",
  "currency": "USD",
  "country": "US",
  "customerIP": "192.168.1.1",
  "items": [
    {
      "code": "PRODUCT_CODE",
      "quantity": 1
    }
  ],
  "billingDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "countryCode": "US"
  },
  "externalReference": "ORDER-12345"
}

Place an Order with Dynamic Products

{
  "token": "your-2pay-token",
  "currency": "USD",
  "country": "US",
  "items": [
    {
      "name": "Custom Service",
      "quantity": 1,
      "price": 99.99,
      "isDynamic": true
    }
  ],
  "billingDetails": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "address1": "456 Oak Ave",
    "city": "Los Angeles",
    "zip": "90001",
    "countryCode": "US"
  }
}

Search Orders

{
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "customerEmail": "customer@example.com",
  "status": "COMPLETE",
  "page": 1,
  "limit": 50
}

Search Subscriptions

{
  "customerEmail": "customer@example.com",
  "status": "Active",
  "recurringEnabled": true,
  "page": 1,
  "limit": 10
}

Update Subscription Payment Method

{
  "subscriptionReference": "SUB123456789",
  "eesToken": "new-2pay-token-from-frontend",
  "holderName": "John Doe"
}

Create a Promotion

{
  "name": "Summer Sale 2024",
  "description": "20% off all products",
  "startDate": "2024-06-01",
  "endDate": "2024-08-31",
  "discountType": "PERCENT",
  "discountValue": 20,
  "couponType": "SINGLE",
  "couponCode": "SUMMER20",
  "productCodes": ["PROD1", "PROD2"],
  "maximumOrders": 1000,
  "applyRecurring": false
}

Report Usage for Metered Billing

{
  "subscriptionReference": "SUB123456789",
  "optionCode": "API_CALLS",
  "units": 1500,
  "usageStart": "2024-01-01",
  "usageEnd": "2024-01-31",
  "description": "January API usage"
}

Pause a Subscription

{
  "subscriptionReference": "SUB123456789",
  "pauseDays": 30
}

Import a Subscription (Migration)

{
  "customerEmail": "customer@example.com",
  "productCode": "PREMIUM_PLAN",
  "startDate": "2024-01-01",
  "expirationDate": "2025-01-01",
  "recurringEnabled": true,
  "quantity": 1,
  "externalCustomerReference": "LEGACY-CUST-123"
}

Set Next Renewal Price

{
  "subscriptionReference": "SUB123456789",
  "price": 19.99,
  "currency": "USD"
}

Architecture

src/
├── index.ts              # MCP server entry point & tool handlers
├── auth/
│   └── authentication.ts # REST header & JSON-RPC session auth
├── tools/
│   ├── orders.ts         # Order management tools
│   ├── subscriptions.ts  # Subscription management tools
│   ├── customers.ts      # Customer management tools
│   ├── products.ts       # Product catalog tools
│   ├── promotions.ts     # Promotion management tools
│   ├── usage.ts          # Usage/metered billing tools
│   ├── leads.ts          # Lead management tools
│   ├── campaigns.ts      # Cross-sell/upsell campaigns
│   ├── shipping.ts       # Shipping management tools
│   ├── sku.ts            # SKU code management
│   ├── account.ts        # Account info tools
│   ├── sso.ts            # Single sign-on tools
│   └── i18n.ts           # Internationalization tools
├── types/
│   └── 2checkout.ts      # TypeScript type definitions
└── utils/
    └── api-client.ts     # REST & JSON-RPC API client

Authentication

The server supports two authentication methods:

1. REST API: Uses X-Avangate-Authentication header with HMAC-SHA256 hash
2. JSON-RPC API: Uses login method to obtain session ID (cached for 30 minutes)

Both methods use SHA-256 by default (MD5 deprecated).

Environment Variables

Security

Important Security Considerations

• Never expose secret keys in client-side code or logs
• Use environment variables for credentials, never hardcode them
• Tokens expire after 30 minutes - generate fresh tokens for each transaction
• EES_TOKEN_PAYMENT has no test mode - tokens must be generated from valid card data
• PCI DSS compliance - Be aware of your compliance requirements when handling payment data

Best Practices

1. Always use HTTPS endpoints
2. Implement proper error handling
3. Log transaction references, not payment details
4. Use sandbox mode during development
5. Regularly rotate API keys

Troubleshooting

Common Errors

Debug Mode

For development, check the configuration resource:

Use the 2pay://config resource to verify your setup

Session Issues

If you encounter session-related errors, the client automatically handles session refresh. If problems persist, restart the MCP server.

API Documentation

• 2Pay.js Integration Guide
• JSON-RPC API 6.0 Reference
• REST API 6.0 Reference
• API Authentication
• Error Codes

Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see the file for details.

Built with the Model Context Protocol SDK.