cardcom-mcp

Tigermedia/cardcom-mcp

3.2

If you are the rightful owner of cardcom-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The CARDCOM MCP Server facilitates integration with the CARDCOM payment gateway, enabling AI assistants to process payments, manage tokens, and create invoices.

Tools
4
Resources
0
Prompts
0

CARDCOM MCP Server

Model Context Protocol (MCP) server for CARDCOM payment gateway integration. This server enables AI assistants to interact with the CARDCOM payment system for processing payments, managing tokens, and creating invoices.

Features

✅ Payment Processing

  • Create payment transactions with iframe/redirect
  • Support for multiple currencies (ILS, USD, EUR)
  • Installment payment support

✅ Token Management

  • Create reusable card tokens
  • Charge tokenized cards for recurring payments
  • Secure card storage without PCI compliance burden

✅ Invoice Generation

  • Create and email invoices
  • Multiple line items support
  • VAT and tax handling

Prerequisites

  • Python 3.10 or higher
  • CARDCOM merchant account
  • CARDCOM API credentials (Terminal ID, Username, API Name, API Password)

Installation

Option 1: Using uvx (Recommended)

The easiest way to use this MCP server is with uvx:

# Install via MCP installer or manually add to Claude Desktop config
uvx cardcom-mcp

Option 2: Manual Installation

  1. Clone this repository:
git clone <repository-url>
cd cardcom-mcp
  1. Install dependencies:
pip install -e .
  1. Set up environment variables:
cp .env.example .env
# Edit .env with your CARDCOM credentials

Configuration

Claude Desktop Configuration

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "cardcom": {
      "command": "uvx",
      "args": ["cardcom-mcp"],
      "env": {
        "CARDCOM_TERMINAL": "YOUR_TERMINAL_ID",
        "CARDCOM_USERNAME": "YOUR_USERNAME",
        "CARDCOM_API_NAME": "YOUR_API_NAME",
        "CARDCOM_API_PASSWORD": "YOUR_API_PASSWORD"
      }
    }
  }
}

Environment Variables

The server uses the following environment variables:

  • CARDCOM_TERMINAL - Your CARDCOM terminal/merchant ID
  • CARDCOM_USERNAME - Your CARDCOM account username
  • CARDCOM_API_NAME - Your API access name
  • CARDCOM_API_PASSWORD - Your API access password

Available Tools

1. create_payment

Create a payment transaction and get a payment URL for customers.

Parameters:

  • amount (required): Amount to charge
  • currency (optional): Currency code (ILS, USD, EUR) - default: ILS
  • success_url (optional): URL to redirect on successful payment
  • error_url (optional): URL to redirect on error
  • description (optional): Payment description/product name
  • customer_name (optional): Customer name
  • language (optional): Interface language (he/en) - default: he

Example:

Create a payment for 150 ILS for "Website Development Services"

Response:

  • Payment URL for customer
  • Transaction code
  • Amount and currency

2. create_token

Create a reusable card token for recurring payments.

Parameters:

  • card_number (required): Credit card number
  • exp_month (required): Expiration month (MM)
  • exp_year (required): Expiration year (YYYY)
  • cvv (optional): Card CVV code
  • customer_name (optional): Cardholder name

Example:

Create a token for card 4580000000000000, expiring 12/2025

Response:

  • Token ID
  • Last 4 digits
  • Expiration date

3. charge_token

Charge a previously created card token.

Parameters:

  • token (required): Card token to charge
  • amount (required): Amount to charge
  • currency (optional): Currency code - default: ILS
  • cvv (optional): Card CVV (if required by merchant settings)
  • num_payments (optional): Number of installments - default: 1
  • description (optional): Charge description
  • reference_id (optional): Unique reference ID for tracking

Example:

Charge token abc123 for 99.90 ILS in 3 installments

Response:

  • Internal deal number
  • Voucher number
  • Amount and installments

4. create_invoice

Create and optionally email an invoice to a customer.

Parameters:

  • amount (required): Total invoice amount
  • customer_name (required): Customer name
  • customer_email (required): Customer email address
  • items (required): Array of invoice line items
    • Each item needs: Description, Price, Quantity
  • language (optional): Invoice language (he/en) - default: he
  • send_email (optional): Send invoice by email - default: true
  • currency (optional): Currency code - default: ILS

Example:

Create invoice for John Doe (john@example.com) with:
- Web hosting: 100 ILS × 1
- Domain registration: 50 ILS × 1
Total: 150 ILS

Response:

  • Invoice number
  • Invoice URL
  • Email status
  • Line items summary

Usage Examples

Example 1: Processing a One-Time Payment

Create a payment for 299 ILS for "Premium Package Subscription" with success URL https://mysite.com/success

The AI will:

  1. Create a payment transaction
  2. Return a payment URL
  3. Customer completes payment via the URL
  4. CARDCOM redirects to your success URL

Example 2: Setting Up Recurring Payments

Step 1: Create a token

Create a token for card 4580111122223333, expiring 03/2026, CVV 123, for customer Sarah Cohen

Step 2: Charge the token monthly

Charge token [returned-token] for 49.90 ILS for "Monthly Subscription - March 2025"

Example 3: Creating an Invoice

Create an invoice for David Levi (david@example.com) with these items:
- Consulting Services: 500 ILS × 4 hours
- Travel Expenses: 120 ILS × 1
Total: 2120 ILS
Send by email in Hebrew

API Endpoints Used

This MCP server interacts with the following CARDCOM API endpoints:

  • https://secure.cardcom.solutions/Interface/BillGoldGetLowProfileIndicator.aspx - Payment and token creation
  • https://secure.cardcom.solutions/interface/ChargeToken.aspx - Token charging
  • https://secure.cardcom.solutions/Interface/CreateInvoice.aspx - Invoice creation

Security Notes

🔒 Important Security Considerations:

  1. Credentials Storage: Never commit .env file to version control
  2. API Credentials: Keep your API credentials secure and rotate them regularly
  3. PCI Compliance: This server handles card data - ensure proper security measures
  4. HTTPS Only: Always use HTTPS for payment URLs and callbacks
  5. Testing: Use test credentials (terminal 1000) for development

Testing

For testing, CARDCOM provides a test terminal:

  • Terminal: 1000
  • Test card: 4580000000000000
  • Any future expiration date
  • Any CVV

Error Handling

The server provides detailed error messages:

  • ❌ Authentication errors (invalid credentials)
  • ❌ Validation errors (missing required fields)
  • ❌ CARDCOM API errors (declined transactions, etc.)
  • ❌ Network errors (timeout, connection issues)

All errors are logged and returned with descriptive messages.

Support

For CARDCOM API documentation and support:

For MCP server issues:

License

MIT License - See LICENSE file for details

Changelog

Version 0.1.1

  • ❌ Removed refund functionality (refund_transaction tool)
  • ✅ Updated documentation to reflect changes

Version 0.1.0 (Initial Release)

  • ✅ Payment processing (low-profile interface)
  • ✅ Token creation and charging
  • ✅ Invoice generation
  • ✅ Multi-currency support
  • ✅ Hebrew and English language support
  • ✅ Comprehensive error handling

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Roadmap

Future enhancements planned:

  • Direct charge API (without redirect)
  • Recurring payment schedules
  • Transaction history and reporting
  • Webhook support for payment notifications
  • Multi-terminal support
  • Enhanced invoice customization
  • Payment link generation with expiration
  • Support for additional CARDCOM features

Made with ❤️ by TigerMedia