使用说明

结账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

配置

标志	必填	默认	说明
`--secretKey`	是	--	您的Checkout.com密钥
`--publicKey`	否	--	您的Checkout.com公钥
`--environment`	没有	`sandbox`	`sandbox` 或 `production`
`--processingChannelId`	否	--	默认处理通道ID

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种工具）

工具	说明
`request_payment`	请求付款。支持令牌、卡、仪器源。包括可选的L2/L3交换数据。
`get_payment`	按ID检索付款的完整详细信息
`get_payment_actions`	获取付款的所有操作（捕获、退款、作废）
`capture_payment`	获取之前授权的付款（全部或部分）
`void_payment`	在捕获之前撤销授权付款
`refund_payment`	退还已扣款项（全部或部分）
`reverse_payment`	撤销付款（自动选择作废或退款）
`increment_payment_authorization`	增加授权金额（酒店/汽车租赁暂停）
`list_payments`	使用过滤器搜索和列出付款（beta）

付款会话（1个工具）

工具	说明
`create_payment_session`	为Checkout.com的托管支付页面创建支付会话

支付链接（2个工具）

工具	说明
`create_payment_link`	创建可共享的支付链接
`get_payment_link`	检索付款链接详细信息

客户（4工具）

工具	说明
`create_customer`	创建新客户
`get_customer`	按ID检索客户
`update_customer`	更新客户详细信息
`delete_customer`	删除客户

仪器（4个工具）

工具	说明
`create_instrument`	从令牌创建存储的支付工具
`get_instrument`	检索仪器详细信息
`update_instrument`	更新工具（到期日、账单地址）
`delete_instrument`	删除工具

争议（5个工具）

工具	说明
`get_dispute`	检索争议（退款）详细信息
`accept_dispute`	接受/承认争议
`get_dispute_evidence`	检索提交的证据
`provide_dispute_evidence`	上传证据以解决争议
`submit_dispute_evidence`	提交证据以供审查

Webhooks（2个工具--只读）

工具	说明
`list_webhooks`	列出所有已配置的Webhook
`get_webhook`	获取webhook的详细信息

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

工具	说明
`get_card_metadata`	按BIN（方案、类型、发卡机构、国家）查找卡元数据

示例提示

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

支付

提示	工具已调用
“使用tok_abc123代币授权25.00美元的付款，暂不捕获”	`request_payment` → `amount: 2500, currency: "USD", source: { type: "token", token: "tok_abc123" }, capture: false`
“全额捕获支付pay_mbv123abc”	`capture_payment` → `payment_id: "pay_mbv123abc"`
“从pay_mbv123abc退款$10”	`refund_payment` → `payment_id: "pay_mbv123abc", amount: 1000`
“无效付款支付_mbv123abc”	`void_payment` → `payment_id: "pay_mbv123abc"`
“显示付款pay_mbv123abc详细信息”	`get_payment` → `payment_id: "pay_mbv123abc"`
“对pay_mbv123abc付款采取了哪些行动？”	`get_payment_actions` → `payment_id: "pay_mbv123abc"`
“列出参考订单-789的付款”	`list_payments` → `reference: "ORDER-789"`

付款会话

提示	工具已调用
“创建一个30.00英镑的付款会话，成功URLhttps://shop.example.com/success，失败URLhttps://shop.example.com/fail"	`create_payment_session` → `amount: 3000, currency: "GBP", success_url: "...", failure_url: "..."`

付款链接

提示	工具已调用
“为订单SHOP-789创建50欧元付款链接”	`create_payment_link` → `amount: 5000, currency: "EUR", reference: "SHOP-789"`
“获取支付链接pl_abc123的状态”	`get_payment_link` → `link_id: "pl_abc123"`

客户

提示	工具已调用
“通过电子邮件创建客户john@example.com并命名为约翰·多伊	`create_customer` → `email: "john@example.com", name: "John Doe"`
“查找客户cus_abc123”	`get_customer` → `customer_id: "cus_abc123"`
“更新客户cus_abc123电子邮件至new@example.com"	`update_customer` → `customer_id: "cus_abc123", email: "new@example.com"`
“删除客户cus_abc123”	`delete_customer` → `customer_id: "cus_abc123"`

仪器

提示	工具已调用
“使用tok_abc代币为客户cus_xyz创建支付工具”	`create_instrument` → `type: "token", token: "tok_abc", customer: { id: "cus_xyz" }`
“获取仪器src_abc123”	`get_instrument` → `instrument_id: "src_abc123"`

争议

提示	工具已调用
“显示争议dsp_abc123”	`get_dispute` → `dispute_id: "dsp_abc123"`
“接受争议dsp_abc123”	`accept_dispute` → `dispute_id: "dsp_abc123"`
“争议dsp_abc123提交了哪些证据？”	`get_dispute_evidence` → `dispute_id: "dsp_abc123"`

网络钩子

提示	工具已调用
“列出所有Webhook”	`list_webhooks` → （无参数）
“显示webhook wh_abc123详细信息”	`get_webhook` → `webhook_id: "wh_abc123"`

卡片元数据

提示	工具已调用
“查找卡BIN 424242”	`get_card_metadata` → `bin: "424242"`

小贴士：您不需要记住确切的字段名称。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 第二步的工具。

使用的关键编程概念

概念	应用地点
`async/await`	每个工具操作员， `CkoClient` 方法，服务器启动
`fetch()` API `CkoClient` --与Checkout.com的所有HTTP通信
Promise链式	响应解析： `fetch()` → `.text()` → `JSON.parse()`
解构	工具处理程序提取参数： `const { customer_id, ...body } = args`
点差运算符	合并默认值： `{ ...args }`，建立请求机构
`try/catch`	每个工具调用和API调用的错误边界
模板文字	URL构造： `/payments/${args.payment_id}/captures`
`Record<string, unknown>` types	类型安全要求主体构造
Zod架构验证	在API调用之前对所有28个工具进行输入验证
模块模式	每个域（支付、客户等）将工具定义导出为命名导出
CLI参数解析	`node:util` `parseArgs` 为了 `--secretKey`, `--environment`等等。
条件对象构建	`if (args.reference) body.reference = args.reference` --仅包括提供的字段

发展

# 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的官方产品。