内容
# centrapay-mcp
[](https://github.com/CedricConday/centrapay-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/centrapay-mcp)
[](./LICENSE)
Centrapay 支付 API 的 MCP 服务器 - 将新西兰支付流程测试直接带入 Claude Code、Claude Desktop 和任何兼容 MCP 的 AI 工具。
询问 Claude 类似问题：
- *"在配置 X 下创建一个 25 新西兰元的支付请求"*
- *"支付请求 abc123 的状态是什么？"*
- *"列出此账户的商户"*
---
## Centrapay 模型
Centrapay 的结构为 **账户 → 商户配置（`configId`）→ 支付请求**。支付请求始终在商户配置下创建，金钱以 `value` 对象表示，金额以**小单位字符串**表示（`{ "amount": "2500", "currency": "NZD" }` = 25.00 新西兰元）。
该服务器直接支持该模型 - 端点、方法和字段名称与实时 API 匹配（参见下面的 *验证*）。
---
## 工具
| 工具 | 功能 | 端点 |
|---|---|---|
| `create_payment_request` | 在 `configId` 下创建请求 | `POST /payment-requests` |
| `get_payment_status` | 通过 ID 获取请求 | `GET /payment-requests/{id}` |
| `void_payment_request` | 作废（取消）请求 | `POST /payment-requests/{id}/void` |
| `list_payment_requests` | 通过 `externalRef` 列出商户账户的请求 | `GET /payment-requests/external-ref/{ref}` |
| `pay_payment_request` | 结算已支付的请求 - **实时调用**（测试或实时取决于密钥 + `assetType`） | `POST /payment-requests/{id}/pay` |
| `create_refund` | 退款已支付的请求（`value` + `idempotencyKey` + `externalRef`） | `POST /payment-requests/{id}/refund` |
| `list_merchants` | API 密钥可见的商户 | `GET /merchants` |
| `get_merchant` | 通过 ID 获取商户详情 | `GET /merchants/{id}` |
| `create_merchant` | 在账户下创建商户 | `POST /merchants` |
身份验证通过 `x-api-key` 头部进行。
---
## 设置
**1. 凭证** - 公共**测试**密钥在 [docs.centrapay.com/api/auth](https://docs.centrapay.com/api/auth) 中有文档记录；对于您自己的商户配置，请联系 [integrations@centrapay.com](mailto:integrations@centrapay.com)。
**2. 安装和构建**
```bash
git clone https://github.com/CedricConday/centrapay-mcp
cd centrapay-mcp
npm install && npm run build
```
**3. 添加到 Claude Code**
```bash
claude mcp add centrapay-mcp node /path/to/centrapay-mcp/dist/index.js \
-e CENTRAPAY_API_KEY=your_key
```
---
## 验证
**请求契约**（端点、方法、主体形状、`x-api-key` 身份验证）通过 **契约测试**（`src/__tests__/payments.test.ts`）固定，这些测试模拟 `fetch` 并断言确切的方法、路径和主体用于 `create` / `pay` / `refund` - 包括所需的退款 `idempotencyKey`。注意：Centrapay **没有单独的沙盒主机** - `service.centrapay.com` 是生产环境，测试或实时取决于您的 API 密钥和结算的资产类型，因此 `pay` / `refund` 是真实的资金转移调用。完整的 `create → pay → refund` 往返需要您自己的商户账户下的 `configId`，因此响应格式保持 **防御性**（已知字段带有回退值，加上原始直传）直到针对实时创建固定。
---
## 为什么
Centrapay 构建了新西兰商户每天使用的支付基础设施。我构建此项目是为了从外部了解他们的 API - 真正集成时的感受和摩擦力。如果您正在面试一位已经围绕您的 API 交付正确 MCP 服务器的候选人，那么他们已经做了相关的调研。
---
## 测试
```bash
npm test
# 测试针对真实源运行（不是重新实现的副本）：
# amount → minor-unit-string 强制转换，和防御性响应格式化。
```
---
## 技术栈
TypeScript · Node.js · `@modelcontextprotocol/sdk` · Centrapay REST API
## 许可证
MIT
