Qut Pay (Kaspi QR payments)

@qutpay/mcp — Qut Pay MCP 服务

Model Context Protocol 服务，适用于 Qut Pay：让 AI Agent（Claude Code、Claude Desktop、Cursor、Windsurf、VS Code Copilot、ChatGPT developer mode…）通过 Qut Pay API 创建 Kaspi QR 账单、读取账单状态、退款，并在沙盒中测试整个流程。仅限哈萨克斯坦，仅支持 KZT。Qut Pay 是独立服务，与 Kaspi Bank 无关联。

安装

你需要从 Qut Pay 管理后台获取 API 密钥（https://qut.kz/app → Integrations → API keys）。请从沙盒密钥（qp_test_…）开始使用——不会有真实资金流动，支付均为模拟操作。

Claude Code：

claude mcp add qutpay -e QUTPAY_API_KEY=qp_test_… -- npx -y @qutpay/mcp

Cursor 一键安装：添加到 Cursor（然后设置你的密钥）。Cursor / Windsurf / Claude Desktop / VS Code（mcp.json、claude_desktop_config.json）：

{
  "mcpServers": {
    "qutpay": {
      "command": "npx",
      "args": ["-y", "@qutpay/mcp"],
      "env": { "QUTPAY_API_KEY": "qp_test_…" }
    }
  }
}

密钥只从环境变量读取，服务不会打印密钥。可选的 QUTPAY_BASE_URL（默认值为 https://api.qut.kz）。

远程（托管）端点

无需安装：https://api.qut.kz/mcp（Streamable HTTP），密钥放在 Authorization: Bearer qp_… 中。Claude Code：claude mcp add --transport http qutpay https://api.qut.kz/mcp --header "Authorization: Bearer qp_test_…"；Cursor/VS Code mcp.json：{ "url": "https://api.qut.kz/mcp", "headers": { "Authorization": "Bearer qp_test_…" } }。未提供密钥时，端点会列出工具并提供文档；工具调用会返回 unauthorized。

工具

工具	功能
qutpay_account	组织、模式（sandbox/live）、资费和限额、收银员、服务商状态——请先调用
qutpay_create_invoice	创建账单（二维码，或通过 kind: "phone" 推送到客户的 Kaspi.kz 应用）；返回 payUrl、qrImageUrl、deepLink、expiresAt。每笔订单传入 idempotencyKey
qutpay_get_invoice	查询单笔账单的状态（live: true 会立即向 Kaspi 查询）
qutpay_list_invoices	按状态、externalOrderId、起止时间、limit ≤ 50 筛选并列出账单
qutpay_cancel_invoice	关闭未完成的账单
qutpay_refund_invoice	全额或部分退款（需要 refunds:write 权限）；使用 live 密钥时需设置 confirm: true
qutpay_simulate_payment	仅限沙盒：将账单标记为已支付 / 失败 / 已过期；Webhook 会正常发送
qutpay_list_subscriptions、qutpay_get_subscription	查询定期账单计划（需要 subscriptions:manage 权限）

资源：qutpay://skill（Agent 技能——集成流程）、qutpay://docs/integration、qutpay://docs/webhook-verify、qutpay://docs/errors、qutpay://docs/openapi。提示词：integrate-checkout（技术栈）、verify-sandbox（金额）。

MCP 服务不提供 API 密钥和 Webhook 端点管理功能：商家需在管理后台创建这些内容，并由 Agent 向商家索取。

典型会话

1. qutpay_account → 模式为 sandbox。
2. qutpay_create_invoice { amount: 100, externalOrderId: "test-1", idempotencyKey: "test-1" } → payUrl。
3. qutpay_simulate_payment { id } → paid；商家的 Webhook 会收到 invoice.paid。
4. qutpay_get_invoice { id } → paid。

文档

• Agent 技能：https://api.qut.kz/SKILL.md · 集成指南：https://api.qut.kz/for-ai · OpenAPI：https://api.qut.kz/openapi.json
• 指南（ru/kk/en）：https://api.qut.kz/docs/guide/mcp
• 状态页：https://status.qut.kz · 信任中心：https://qut.kz/en/trust/

MIT。