liqpay-mcp-server

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

Install in VS Code

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