Checkout MCP Server

结账mcp

免责声明：这是一个 非官方的社区建设项目。它是 不 与以下机构有关联、得到其认可或与之有正式联系 Checkout.com 或Checkout有限公司“Checkout.com”是Checkout有限公司的注册商标。此工具使用公开的Checkout.com REST API，需要您自己的有效API证书。所有开发和测试都是专门针对Checkout.com进行的 沙盒（测试）环境 出于教育和学习目的，没有进行现场/制作交易。

模型上下文协议（MCP）服务器，将任何兼容MCP的客户端连接到 Checkout.com API允许直接从IDE或自动化工具对支付、客户、争议、Webhook等进行编程访问。

28工具 跨8个域：支付（具有L2/L3交换）、支付会话、支付链接、客户、工具、争议、Webhooks（只读）和卡元数据。

快速开始

# Install
npm install -g checkout-mcp

# Or run directly with npx
npx checkout-mcp --secretKey sk_sbox_your_key_here

配置

MCP客户端配置

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "checkout": {
      "command": "npx",
      "args": ["-y", "checkout-mcp", "--secretKey", "sk_sbox_your_key_here"]
    }
  }
}

克劳德桌面（带所有选项）

{
  "mcpServers": {
    "checkout": {
      "command": "npx",
      "args": [
        "-y", "checkout-mcp",
        "--secretKey", "sk_sbox_your_key_here",
        "--publicKey", "pk_sbox_your_key_here",
        "--processingChannelId", "pc_your_channel_id",
        "--environment", "sandbox"
      ]
    }
  }
}

光标

添加 .cursor/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "checkout": {
      "command": "npx",
      "args": ["-y", "checkout-mcp", "--secretKey", "sk_sbox_your_key_here"]
    }
  }
}

VS代码（副本）

添加 .vscode/mcp.json:

{
  "servers": {
    "checkout": {
      "command": "npx",
      "args": ["-y", "checkout-mcp", "--secretKey", "sk_sbox_your_key_here"]
    }
  }
}

工具参考

付款（9种工具）

付款会话（1个工具）

支付链接（2个工具）

客户（4工具）

仪器（4个工具）

争议（5个工具）

Webhooks（2个工具--只读）

卡片元数据（1个工具）--测试版

示例提示

连接MCP服务器后，在LLM客户端上使用自然语言。LLM读取每个工具的模式，并将您的单词映射到正确的API调用。

支付

付款会话

付款链接

客户

仪器

争议

网络钩子

卡片元数据

小贴士：您不需要记住确切的字段名称。LLM读取工具模式并将您的自然语言转换为正确的API调用，包括将美元金额转换为小单位（例如25.00美元→ 2500).

2/3级交换数据

这 request_payment 该工具支持L2和L3交换数据，以降低商业/公司卡的处理费用：

Level 2: customer_reference, tax_amount, tax_rate, postal_code
Level 3: All L2 fields + freight_amount, duty_amount, ship_from_postal_code, line_items[]

示例提示：

“处理4242卡上的50美元付款…带有2级数据——订单号CORP-123，税款4.50美元”

测试

# Unit tests (37 tests across 9 files)
npm test

# TypeScript type check
npm run lint

# Live sandbox integration test (requires .env with CKO_SECRET_KEY and CKO_PROCESSING_CHANNEL_ID)
source .env && export CKO_SECRET_KEY CKO_PROCESSING_CHANNEL_ID && node test-live.mjs

看 测试_结果.md 了解完整的测试结果和方法。

背景

该项目基于两个现有Checkout.com项目的模式和集成逻辑构建：

Cko流量网络 --付款会话/流程

Flow集成是主要影响因素。延续的关键模式：

• 直接的 fetch() 使用Bearer令牌身份验证的调用 --Flow服务器向以下对象发出原始HTTP请求 https://api.sandbox.checkout.com/payment-sessions 随着 Authorization: Bearer ${SECRET_KEY} 和 Content-Type: application/json 标题。这种确切的模式成为了 CkoClient 类在所有28个工具中使用。官方的 checkout-sdk-node 与现代Node.js的ESM/CJS兼容性问题尚未解决，因此直接获取方法（已在Flow项目中得到验证）是正确的调用。
• 请求车身构造 --Flow服务器构建完整的支付会话有效负载： amount, currency, success_url, failure_url, billing, shipping, customer, billing_descriptor, items[], risk, metadata，以及 processing_channel_idThe create_payment_session 该工具反映了这种精确的身体结构和场映射。
• 3ds 密钥重映射 --在Flow服务器中，3D Secure以以下方式发送 "3ds": { "enabled": true } 在JSON正文中。由于JavaScript标识符不能以数字开头，因此该工具接受 three_ds 作为输入并将其重新映射到 "3ds" 在发送到API之前。同样的模式，同样的原因。
• async/await 随着 fetch() --Flow服务器使用 async 路由处理程序 await fetch(...) 紧随其后 await request.json() 解析响应。这 CkoClient 遵循相同的异步流： await fetch() → await res.text() → JSON.parse()，在解析步骤周围添加了错误处理。
• 基于Promise的响应处理 --Flow服务器链 .json() 在获取响应后，将解析结果直接传递给 res.send()MCP工具遵循相同的模式：客户端解析为解析的JSON，工具处理程序按原样返回它，以便MCP框架进行序列化。

React支付应用 -统一支付API/仪表板

支付仪表板提供了统一支付API请求和代理模式：

• 卡源架构 --仪表板直接发布到 POST /payments 随着 source: { type: "card", number: "4242424242424242", expiry_month: "01", expiry_year: "25", cvv: "100" }，加 amount, currency, reference，以及 processing_channel_idThe request_payment 该工具支持这种用于沙盒测试的精确源代码结构。
• API调用的代理模式 --仪表板通过服务器端路由客户端请求 /proxy 端点使用 axios({ method, url, headers, data }) 避免CORS。MCP服务器的工作原理相同-它位于客户端（MCP主机）和Checkout.com API之间，通过正确的验证头转发结构化请求。
• async/await 随着 try/catch 错误处理 -仪表板中的每个路由处理程序都将API调用封装在 try { ... } catch (err) { res.status(500).json({ error }) }MCP工具调用层使用相同的模式：每个工具调用都封装在 try/catch，返回的错误为 { isError: true, content: [{ text: "Error: ..." }] } 而不是使服务器崩溃。
• MongoDB持久模式 --仪表板存储付款响应 await collection.insertOne(responseToSave) 以便以后通过以下方式检索 /api/paymentDetails虽然MCP服务器本身不持久化数据，但始终使用相同的异步数据处理模式（等待操作、返回结果、捕获错误）。
• 两步支付流程 --仪表板通过发布演示了授权然后捕获 capture: false 并跟踪授权状态。这就是为什么MCP服务器将其拆分为 request_payment （与 capture 标志）和一个单独的 capture_payment 第二步的工具。

使用的关键编程概念

发展

# Install deps
npm install

# Type check
npm run lint

# Build
npm run build

# Run tests
npm test

# Dev mode (auto-reload)
npm run dev -- --secretKey sk_sbox_your_key

建筑

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Client                               │
│           (Claude Desktop / Cursor / VS Code / etc.)            │
└──────────────────────────┬──────────────────────────────────────┘
                           │ JSON-RPC over stdio
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                     checkout-mcp server                         │
│                                                                 │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────────┐     │
│  │ McpServer    │   │ StdioServer  │   │ Configuration    │     │
│  │ (tool reg)   │◄──│ Transport    │   │ (CLI args parse) │     │
│  └──────┬───────┘   └──────────────┘   └──────────────────┘     │
│         │                                                       │
│         │  routes to tool handler                               │
│         ▼                                                       │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    Tool Registry                        │    │
│  │                                                         │    │
│  │  ┌──────────┐ ┌──────────┐ ┌────────┐ ┌─────────────┐  │    │
│  │  │ Payments │ │ Sessions │ │ Links  │ │  Customers  │  │    │
│  │  │ (9)      │ │ (1)      │ │ (2)    │ │  (4)        │  │    │
│  │  └──────────┘ └──────────┘ └────────┘ └─────────────┘  │    │
│  │  ┌──────────┐ ┌──────────┐ ┌────────┐ ┌─────────────┐  │    │
│  │  │Instruments│ │ Disputes │ │Webhooks│ │Card Metadata│  │    │
│  │  │ (4)      │ │ (5)      │ │ (2)    │ │ (1) beta    │  │    │
│  │  └──────────┘ └──────────┘ └────────┘ └─────────────┘  │    │
│  └─────────────────────┬───────────────────────────────────┘    │
│                        │                                        │
│                        ▼                                        │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    CkoClient                            │    │
│  │          Thin HTTP wrapper over native fetch()          │    │
│  │       POST / GET / PUT / PATCH / DELETE methods         │    │
│  └─────────────────────────┬───────────────────────────────┘    │
│                            │                                    │
└────────────────────────────┼────────────────────────────────────┘
                             │ HTTPS (Bearer token auth)
                             ▼
┌────────────────────────────────────────────────────────────────┐
│                  Checkout.com REST API                         │
│          api.sandbox.checkout.com (sandbox)                    │
│          api.checkout.com (production)                         │
└────────────────────────────────────────────────────────────────┘

设计决策

• 基于SDK的统一支付API --官方 checkout-sdk-node 与现代Node.js存在未解决的模块兼容性问题（ESM/CJS冲突）。薄 CkoClient 使用本地 fetch() 直接调用Unified Payments API，使捆绑包保持较小，并对请求构造进行完全控制。
• 标准运输 --服务器使用JSON-RPC通过stdin/stdout进行通信，JSON-RPC是标准的MCP传输。没有要配置的HTTP服务器，没有要打开的端口。
• 每个工具的Zod模式 --每个工具都使用Zod声明其输入模式。MCP SDK使用这些来生成JSON模式，用于客户端验证和工具发现。
• 单个CJS捆绑包 — tsup 将所有内容编译成一个约31KB的文件。没有运行时转译，没有模块解析问题。
• 处理通道注入 --如果 --processingChannelId 在启动时提供，它会自动注入到接受它的工具中，因此调用者不需要每次都传递它。

项目结构

checkout-mcp-server/
├── src/
│   ├── index.ts                 # Entry point — server setup, tool registration
│   ├── client.ts                # CkoClient — HTTP wrapper for Checkout.com API
│   ├── configurations/
│   │   └── configurations.ts    # CLI argument parsing and validation
│   └── tools/
│       ├── types.ts             # Tool interface definition
│       ├── tools.ts             # Master tool registry (all 28 tools)
│       ├── payments/            # 9 tools — full payment lifecycle + L2/L3
│       ├── payment-sessions/    # 1 tool — hosted payment sessions
│       ├── payment-links/       # 2 tools — shareable payment links
│       ├── customers/           # 4 tools — CRUD
│       ├── instruments/         # 4 tools — stored payment methods
│       ├── disputes/            # 5 tools — chargeback management
│       ├── webhooks/            # 2 tools — event notification queries (read-only)
│       └── card-metadata/       # 1 tool — BIN lookup (beta)
├── test/                        # Unit tests (vitest)
├── dist/                        # Build output (CJS bundle)
├── .env.example                 # Template for credentials
└── package.json

安全

• API密钥在运行时作为CLI参数传递-从不硬编码
• 使用 .env 本地文件并将其添加到 .gitignore
• 服务器在启动时验证密钥格式（警告环境/密钥前缀不匹配）
• 所有API通信都使用带有承载令牌身份验证的HTTPS
• MCP响应中未记录或包含任何密钥
• 原始卡号在生产模式下被阻止——使用令牌或保存的工具代替
• 所有HTTP请求都有30秒的超时时间，以防止挂起连接

备注：这是一个“按原样”提供的开源工具，不提供任何保证。在使用生产凭据之前，请查看源代码并了解每个工具的功能。你对如何使用它负责。

需求

• Node.js 18+
• 使用API密钥的Checkout.com帐户(获取沙盒密钥)

许可证

麻省理工学院——见 许可证 了解详情。

______________________________________________________________________

*该项目由以下人员独立维护 伊恩·哈穆德 并且不是Checkout.com的官方产品。*