MCP server for the LiqPay payment gateway — Ukraine's dominant payment platform operated by PrivatBank.

Exposes 11 tools for payments, holds, refunds, subscriptions, payouts, and webhook verification to AI agents and LLM workflows via the Model Context Protocol.

Features

• 11 tools covering the full LiqPay API: payments, holds, refunds, subscriptions, P2P payouts, webhooks
• PCI DSS safe — hosted checkout keeps card data on LiqPay's side
• 2-step hold flow — freeze funds first, capture or cancel later
• Recurring subscriptions — daily, weekly, monthly, yearly billing cycles
• Webhook verification — SHA-1 signature validation for incoming callbacks
• Truncation protection — large report responses are automatically truncated with guidance
• TypeScript — full type safety, strict mode, zero any
• Zero extra dependencies — uses Node.js built-in crypto and native fetch

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "liqpay": {
      "command": "npx",
      "args": ["-y", "liqpay-mcp-server"],
      "env": {
        "LIQPAY_PUBLIC_KEY": "your_public_key",
        "LIQPAY_PRIVATE_KEY": "your_private_key"
      }
    }
  }
}

VS Code / Cursor

Or add to .vscode/mcp.json / .cursor/mcp.json manually:

{
  "servers": {
    "liqpay": {
      "command": "npx",
      "args": ["-y", "liqpay-mcp-server"],
      "env": {
        "LIQPAY_PUBLIC_KEY": "your_public_key",
        "LIQPAY_PRIVATE_KEY": "your_private_key"
      }
    }
  }
}

Claude Code (CLI)

Add to ~/.claude/settings.json (global) or .claude/settings.json (project):

{
  "mcpServers": {
    "liqpay": {
      "command": "npx",
      "args": ["-y", "liqpay-mcp-server"],
      "env": {
        "LIQPAY_PUBLIC_KEY": "your_public_key",
        "LIQPAY_PRIVATE_KEY": "your_private_key"
      }
    }
  }
}

Prerequisites

• Node.js >= 18
• LiqPay merchant account — get your keys at liqpay.ua/en/adminbusiness

Tools

| Tool | Description | Annotations | |------|-------------|-------------| | liqpay_create_checkout_url | Generate a hosted checkout URL (PCI DSS safe) | idempotent open-world | | liqpay_get_payment_status | Fetch payment status by order ID | read-only idempotent open-world | | liqpay_get_payments_list | List payments by date range (max 31 days) | read-only idempotent open-world | | liqpay_create_hold | Pre-authorize funds on a card (2-step) | open-world | | liqpay_complete_hold | Capture previously held funds | destructive open-world | | liqpay_cancel_hold | Release held funds back to payer | destructive idempotent open-world | | liqpay_create_refund | Refund a completed payment (full/partial) | destructive open-world | | liqpay_create_subscription | Create recurring subscription via checkout | idempotent open-world | | liqpay_cancel_subscription | Cancel an active subscription | destructive idempotent open-world | | liqpay_create_payout | P2P transfer to a card | destructive open-world | | liqpay_verify_callback | Validate incoming webhook signature | read-only idempotent |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | LIQPAY_PUBLIC_KEY | Yes | Merchant public key from LiqPay dashboard | | LIQPAY_PRIVATE_KEY | Yes | Merchant private key from LiqPay dashboard |

Rate Limits

| Scope | Limit | |-------|-------| | All API requests | ~100 req/min per merchant account | | Reports (liqpay_get_payments_list) | Max 31-day date range per request | | Checkout URL generation | No limit — computed locally, no API call | | Webhook verification | No limit — computed locally, no API call |

Docker

docker build -t liqpay-mcp-server .
docker run -e LIQPAY_PUBLIC_KEY=your_key -e LIQPAY_PRIVATE_KEY=your_secret liqpay-mcp-server

Or with docker-compose:

services:
  liqpay-mcp:
    build: .
    environment:
      LIQPAY_PUBLIC_KEY: your_key
      LIQPAY_PRIVATE_KEY: your_secret

Development

# Install dependencies
npm install

# Run in dev mode (auto-reload)
npm run dev

# Build
npm run build

# Run tests
npm test

# Test with MCP Inspector
LIQPAY_PUBLIC_KEY=test LIQPAY_PRIVATE_KEY=test \
  npx @modelcontextprotocol/inspector node dist/index.js

See docs/SANDBOX_TESTING.md for testing without real money.

Documentation

| Document | Description | |----------|-------------| | docs/AGENT_SETUP.md | Instructions for AI agents to install and configure this server | | docs/API_REFERENCE.md | Complete tool reference with request/response examples | | docs/SANDBOX_TESTING.md | How to test with LiqPay sandbox (no real money) |

Security

• LiqPay API signature uses SHA-1: base64(sha1(private_key + data + private_key))
• Private keys are never logged or included in tool responses
• liqpay_create_hold and liqpay_create_payout accept raw card numbers — ensure PCI DSS compliance
• For most payment use cases, prefer liqpay_create_checkout_url which handles card data on LiqPay's side

License

MIT