payware

payware MCP 服务

用于集成 payware 支付 API 的官方 MCP（Model Context Protocol）服务。此服务支持 AI 助手与 payware API 交互，为所有合作伙伴类型自动化集成工作流。

版本发布到 npm，包名为 @payware/mcp-server；同时发布到官方 MCP Registry，名称为 io.github.payware/mcp-server。采用 MIT 许可，详见 LICENSE。

适用对象

• 商户 - 接受付款、管理产品、生成交易报告
• ISV（独立软件供应商） - 使用 OAuth2 令牌管理构建多商户平台
• 支付机构 - 处理 A2A 转账，并通过多种支付方式支持 Payment Choice Architecture

v1.2.0 新功能

• SHA-256 身份验证 - JWT 内容哈希已从 MD5 升级为 SHA-256（contentSha256 标头）
• 错误代码更新 - 新增错误代码：ERR_INVALID_CONTENT_HASH、ERR_MISSING_CONTENT_HASH
• 向后兼容 - 保留已弃用的 MD5 函数，以支持旧版集成

功能

🔐 身份验证工具

• RSA 密钥生成：生成安全的 2048 位 RSA 密钥对
• JWT 令牌创建：创建格式正确的 JWT 令牌
• 沙盒设置：配置沙盒身份验证

💳 交易工具

• 创建交易：支持 PLAIN、QR 和 BARCODE 交易
• 处理交易：支持 Payment Choice Architecture 的交易处理
• 交易状态：按 ID 查询交易状态
• 交易历史：获取已完成交易的详情
• 回调模拟：为商户和支付机构测试回调场景

📍 交互点（POI）工具

• 设置价格：为 POI 配置金额、币种和支付详情
• 取消价格：清除 POI 中的当前价格
• 获取 POI：获取 POI 详情及当前状态
• 获取状态：查询 POI 交易状态
• 获取二维码：生成 POI 支付二维码
• 列出 POI：列出某商户的所有 POI

📣 活动、投放位和播出工具

适用于商户，以及代表商户行事的 ISV。修改需要商户的 PRM 方案；所有方案均支持读取。

• 投放位：通过海报、电视广告、包装、链接或标签推广产品；每个投放位都有自己的 pl ID，因此由其发起的每笔付款都会归因于该投放位。包含每个投放位的二维码、条形码和短链接
• 活动：跨产品归类投放位，并查看汇总结果
• 播出规则：安排投放位的播出时间，支持重复规则、时间窗口和时区，并可通过一次调用替换整个日程
• 播出日历：查看指定时间范围内所有产品的播出安排
• 结果：按投放位或活动查看展示的优惠、发起和确认的付款，以及确认金额

📋 日志工具（高级版）

• 查询日志：按级别、日志记录器、消息内容和日期范围搜索和筛选应用日志
• 日志状态：查看日志可用性和存储信息
• 下载日志：获取压缩日志归档，以便离线分析

🛠️ 实用工具

• 高级代码生成：生成涵盖 8 种语言（Python、Node.js、PHP、Java、C#、Go、Ruby、cURL）的完整集成代码，支持 16 种以上框架
• 框架集成：提供针对 Django、FastAPI、Express、NestJS、Laravel、Spring Boot、ASP.NET 等框架的示例
• 真实场景：生成完整的集成场景（电子商务、ISV 多商户、P2P 支付）
• 全面文档：自动生成包含代码示例的完整 API 文档
• 请求格式化：格式化并验证 API 请求

快速开始

1. 安装

通过 npm 安装（推荐）：

npm install -g @payware/mcp-server

从源代码安装：

git clone https://github.com/payware/mcp-server.git
cd mcp-server
npm install

2. 环境配置

复制示例环境文件并配置凭据：

cp .env.example .env

编辑 .env 文件：

# Partner ID from payware dashboard
PAYWARE_PARTNER_ID=your_partner_id_here

# Path to private key file (relative to project root)
PAYWARE_SANDBOX_PRIVATE_KEY_PATH=keys/sandbox-your-private-key.pem
PAYWARE_PRODUCTION_PRIVATE_KEY_PATH=keys/production-your-private-key.pem

# Optional: Sandbox base URL (defaults to https://sandbox.payware.eu/api)
PAYWARE_SANDBOX_URL=https://sandbox.payware.eu/api

⚠️ 安全提示：切勿将 .env 文件提交到版本控制中。该文件包含敏感凭据。

选择工具集

每轮对话中，每个工具定义都会加入助手的上下文，而商户拥有 70 多个工具。若只想提供你使用的工具组，请将 PAYWARE_MCP_TOOLSETS 设置为以逗号分隔的列表：

PAYWARE_MCP_TOOLSETS=products,placements

工具集：auth、transactions、products、placements、data、logs、poi、shops、onboarding、utils。未设置或设为 all 时，将加载所有工具。未知名称会被忽略，并在服务日志中发出警告。不属于所选工具集的工具既不会列出，也无法调用；这会缩小提供给助手的工具范围，但不会改变合作伙伴账户的权限。通过此服务获取 OAuth2 令牌的 ISV 需包含 auth。

3. 启动 MCP 服务

npm start

4. 基本集成流程

1. 生成 RSA 密钥

   Tool: payware_authentication_generate_rsa_keys
   

2. 创建 JWT 令牌

   Tool: payware_authentication_create_jwt_token
   Parameters:
   - partnerId: (from PAYWARE_PARTNER_ID)
   - privateKey: (from environment-specific key path)
   

3. 设置沙盒

   Tool: payware_authentication_setup_sandbox_auth
   Parameters:
   - partnerId: (from PAYWARE_PARTNER_ID)
   

4. 创建交易

   Tool: payware_operations_create_transaction
   Parameters:
   - partnerId: (from PAYWARE_PARTNER_ID)
   - privateKey: (from environment-specific key path)
   - amount: 10.00
   - currency: EUR
   - reasonL1: "Payment description"
   - type: PLAIN
   

5. 检查状态

   Tool: payware_operations_get_transaction_status
   Parameters:
   - partnerId: (from PAYWARE_PARTNER_ID)
   - privateKey: (from environment-specific key path)
   - transactionId: TRANSACTION_ID
   

API 请求结构

payware MCP 服务会将扁平参数输入转换为 payware API 所需的正确嵌套 JSON 结构：

创建交易请求结构

{
  // ROOT LEVEL - Transaction metadata
  "shop": "SHOP001",                    // Optional: Shop code
  "account": "GB29NWBK60161331926810",  // Optional: Account identifier
  "friendlyName": "Your Shop Name",     // Optional: Account holder name
  "callbackUrl": "https://callback.url", // Optional: HTTPS callback URL
  "passbackParams": "{\"orderId\":\"12345\"}", // Optional: Callback parameters
  
  // TRANSACTION DATA - Required transaction information
  "trData": {
    "amount": "25.50",              // String/Number: Amount (can be "0.00" for flexible amounts)
    "currency": "EUR",              // REQUIRED: ISO 3-character currency code
    "reasonL1": "Payment for services", // REQUIRED: Transaction description (max 100 chars)
    "reasonL2": "Order #12345"      // Optional: Additional description (max 100 chars)
  },
  
  // TRANSACTION OPTIONS - Transaction behavior settings
  "trOptions": {
    "type": "QR",                   // PLAIN, QR, or BARCODE (default: PLAIN)
    "timeToLive": 300               // Seconds: 60-600 (default: 120)
  },
  
  // QR OPTIONS - Only included when type=QR
  "qrOptions": {
    "qrFormat": "PNG",              // PNG, SVG, JPG, GIF, BMP (default: SVG)
    "qrBorder": 4,                  // Border modules: 1-10 (default: 4)
    "qrErrorCorrection": "QUARTILE", // LOW, MEDIUM, QUARTILE, HIGH (default: QUARTILE)
    "qrScale": 16,                  // Pixel size: 1-100 (default: 16, irrelevant for SVG)
    "qrVersion": 10                 // QR version: 1-40 (default: 10, auto if not specified)
  },
  
  // BARCODE OPTIONS - Only included when type=BARCODE
  "barOptions": {
    "barFormat": "SVG",             // PNG, SVG, JPG (default: SVG)
    "barModuleWidth": 2,            // Module width: 1-10 (default: 2)
    "barBarHeight": 100,            // Height: 15-1000 (default: 100)
    "barFontSize": 12,              // Font size: 0-24 (default: 12)
    "barHumanReadableLocation": "NONE" // NONE, BOTTOM, TOP (default: NONE)
  }
}

参数映射

使用 MCP 工具时，参数会自动映射到正确的 API 结构：

MCP 工具参数	API 位置	说明
partnerId、privateKey	身份验证	用于 JWT 签名，不会在请求中发送
account、friendlyName、shop、callbackUrl、passbackParams	根级别	交易元数据
amount、currency、reasonL1、reasonL2	trData 对象	核心交易数据
type、timeToLive	trOptions 对象	交易行为
qrFormat、qrBorder 等	qrOptions 对象	QR 码设置（当 type=QR 时）
barFormat、barModuleWidth 等	barOptions 对象	条形码设置（当 type=BARCODE 时）

可用工具

代码生成与文档

payware_generate_code_example

支持框架的高级多语言代码生成

支持所有合作伙伴类型的 60 多项操作：

• 交易：create_transaction、get_transaction_status、cancel_transaction、process_transaction、get_transaction_history、simulate_callback
• 产品：create_product、get_product、update_product、delete_product、list_products、get_product_image、create_schedule、update_schedule、delete_schedule、list_schedules
• OAuth2（仅 ISV）：obtain_token、get_token_info、create_token_simple、refresh_token、revoke_token、list_active_tokens
• 数据：generate_report、get_report_status、export_report、download_export、cancel_report、list_reports、get_analytics_summary、create_custom_report
• P2P（支付机构）：initiate_p2p_transfer、accept_p2p_transfer、reject_p2p_transfer、get_p2p_transfer_status、list_p2p_transfers、cancel_p2p_transfer、create_p2p_link、get_p2p_analytics
• Soundbites（支付机构）：register_audio、get_audio、update_audio、delete_audio、list_audios、create_soundbite_transaction、stream_audio、download_audio、get_soundbite_analytics、create_audio_playlist、get_audio_preview

payware_generate_documentation

全面的文档生成器

针对任意合作伙伴类型和编程语言组合，生成包含可运行代码示例的完整 API 文档。

身份验证

payware_authentication_generate_rsa_keys

生成用于 API 身份验证的 RSA 密钥对。

参数：

• keySize（可选）：RSA 密钥大小，单位为位（默认值：2048）

payware_authentication_create_jwt_token

创建用于 API 身份验证的 JWT 令牌。

参数：

• partnerId（必填）：来自 payware 的合作伙伴 ID
• privateKey（必填）：PEM 格式的 RSA 私钥

payware_authentication_validate_jwt

验证 JWT 令牌的格式和签名。

参数：

• token（必填）：要验证的 JWT 令牌
• partnerId（必填）：用于验证的合作伙伴 ID

payware_authentication_test_jwt

使用 payware API 测试 JWT 令牌。

参数：

• token（必填）：要测试的 JWT 令牌
• partnerId（必填）：合作伙伴 ID

payware_authentication_setup_sandbox_auth

设置沙盒身份验证配置。

参数：

• partnerId（必填）：来自 payware 的合作伙伴 ID
• privateKey（可选）：用于验证的私钥

交易

交易状态概览

payware 交易可能具有以下状态：

ACTIVE 状态：

• ⏳ ACTIVE：交易处于活动状态，等待处理或完成
• 这是 payware_transactions_get_transaction_status 返回的唯一状态
• 使用 GET /transactions/{id} 端点

最终状态：

• ✅ CONFIRMED：已成功完成
• ❌ DECLINED：被用户、处理中或完成付款的金融机构拒绝
• 💥 FAILED：因技术原因或其他原因失败
• ⏰ EXPIRED：交易的生存时间已过
• 🚫 CANCELLED：交易发起方已取消

这些最终状态只能通过 payware_operations_get_transaction_history，使用 GET /transactions-history/{id} 端点获取。

payware_operations_create_transaction

创建新交易，支持完整的 API 结构。

关键参数：

• currency（必填）：ISO 3 字符代码（EUR、USD、GBP 等）
• reasonL1（必填）：交易描述（最多 100 个字符）
• partnerId（必填）：来自 payware 控制面板的合作伙伴 ID
• privateKey（必填）：用于 JWT 签名的 RSA 私钥
• amount（可选）：货币金额（默认值：灵活金额为 "0.00"）
• type（可选）：PLAIN、QR 或 BARCODE（默认值：PLAIN）
• timeToLive（可选）：付款超时时间，单位为秒，范围为 60–600（默认值：120）

QR 选项（当 type=QR 时）：

• qrFormat：PNG、SVG、JPG、GIF、BMP（默认值：SVG）
• qrErrorCorrection：LOW、MEDIUM、QUARTILE、HIGH（默认值：QUARTILE）
• qrScale、qrBorder、qrVersion：尺寸和外观设置

条码选项（当 type=BARCODE 时）：

• barFormat：PNG、SVG、JPG（默认值：SVG）
• barModuleWidth、barBarHeight、barFontSize：尺寸设置

payware_operations_get_transaction_status

仅获取 ACTIVE 交易的状态。对于已完成或最终确定的交易，请使用历史记录工具。

参数：

• transactionId（必填）：交易 ID（以 'pw' 开头）
• partnerId（必填）：合作伙伴 ID
• privateKey（必填）：用于 JWT 签名的私钥

payware_operations_simulate_callback

模拟回调场景以进行测试。

参数：

• transactionId（必填）：交易 ID
• status（可选）：CONFIRMED、DECLINED、FAILED、EXPIRED 或 CANCELLED（默认值：CONFIRMED）
• callbackUrl（可选）：发送回调的 URL
• amount（可选）：交易金额（默认值：10.00）
• currency（可选）：货币（默认值：EUR）
• type（可选）：交易类型（默认值：PLAIN）

实用工具

payware_generate_code_example

为任意 payware 操作生成可用于生产环境的代码示例。

参数：

• operation（必填）：要生成代码的操作——请参阅下方完整列表
• language（可选）：python、nodejs、php、java、csharp、curl（默认值：python）
• partner_type（可选）：merchant、isv、payment_institution（默认值：merchant）
• include_comments（可选）：是否包含详细的代码注释（默认值：true）
• include_error_handling（可选）：是否包含全面的错误处理（默认值：true）

按类别划分的可用操作：

身份验证：

• authentication - JWT 身份验证设置

交易操作（适用于所有合作伙伴类型）：

• create_transaction - 创建新的支付交易
• get_transaction_status - 获取交易状态和详情
• process_transaction - 处理待处理的交易
• cancel_transaction - 取消待处理的交易

产品操作（merchant、isv）：

• create_product - 创建新产品
• get_product - 获取产品详情
• list_products - 列出所有产品

POI 操作（isv）：

• set_price - 在交互点设备上设置价格
• cancel_price - 取消 POI 上的有效价格
• get_poi - 获取 POI 详情
• get_poi_status - 获取 POI 交易状态
• get_poi_qrcode - 为 POI 生成二维码
• list_pois - 列出商家的所有 POI

OAuth2 操作（仅限 isv）：

• obtain_token - 获取 OAuth2 访问令牌
• get_token_info - 获取 OAuth2 令牌信息

数据操作（适用于所有合作伙伴类型）：

• generate_report - 生成分析报告
• get_report_status - 获取报告生成状态

P2P 操作（仅限 payment_institution）：

• initiate_p2p_transfer - 发起点对点转账
• accept_p2p_transfer - 接受 P2P 转账

Soundbites（仅限 payment_institution）：

• register_audio - 为 soundbite 交易注册音频内容

payware_generate_documentation

生成包含代码示例的完整 API 文档。

参数：

• language（可选）：目标编程语言（默认值：python）
• partnerType（可选）：merchant、isv、payment_institution（默认值：merchant）
• includeScenarios（可选）：是否包含真实场景的集成示例（默认值：true）
• outputFormat（可选）：markdown、html、json（默认值：markdown）

payware_utils_format_request

使用确定性 JSON 序列化来格式化和验证 API 请求，确保 SHA-256 计算一致。

参数：

• type（必填）：transaction、headers 或 curl
• data（可选）：要格式化的数据
• jwtToken（可选）：用于请求头的 JWT 令牌
• signature（可选）：请求签名
• endpoint（可选）：用于 curl 的 API 端点
• method（可选）：HTTP 方法（默认值：POST）

payware_utils_format_json_deterministic

按照确定性的属性顺序格式化 JSON，确保 SHA-256 计算一致。

参数：

• data（必填）：要序列化的对象
• minimize（可选）：移除空白字符（默认值：true）

payware_utils_server_info

获取 MCP 服务信息和配置。

注意： 所有交易数据都使用一致的属性顺序进行序列化，以防止内容哈希不匹配错误。

依赖项

• @modelcontextprotocol/sdk：MCP 服务框架
• axios：用于 API 调用的 HTTP 客户端
• jsonwebtoken：JWT 令牌创建
• node-forge：RSA 密钥生成

环境

• 仅限沙盒：所有 API 调用均限制在沙盒环境中
• 基础 URL：https://sandbox.payware.eu/api/v1
• 支持的货币：EUR、USD、GBP
• 支持的交易类型：PLAIN、QR、BARCODE

安全

⚠️ 重要安全提示：

环境变量

• 必需：所有凭据都必须使用环境变量
• 切勿将 .env 文件提交到版本控制系统
• 开发环境和生产环境请使用不同的凭据
• 将私钥文件存储在 Web 无法访问的目录之外

私钥安全

• 为沙盒和生产环境分别生成密钥对
• 使用受限的文件权限（600）存储私钥
• 切勿将私钥嵌入源代码
• 根据安全策略定期轮换密钥

API 安全

• 此服务仅用于沙盒测试
• 切勿在生产环境中使用沙盒密钥
• 在生产环境中实施适当的错误处理
• 所有 API 通信均使用 HTTPS
• 验证所有输入参数
• 实施速率限制和监控

JSON 序列化与 SHA-256 一致性

⚠️ 重要：payware API 要求使用确定性 JSON 序列化来计算 SHA-256

• 属性顺序：JSON 对象的属性顺序必须保持一致
• 最小化格式：请求正文中不得包含空白字符或格式化内容
• SHA-256 计算：必须基于发送给 API 的完全相同的 JSON 字符串进行计算
• 实现方式：此服务使用确定性 JSON 序列化来确保一致性

正确的 JSON 格式示例：

{"trData":{"amount":"25.50","currency":"EUR","reasonL1":"Payment description"},"trOptions":{"timeToLive":300,"type":"PLAIN"}}

原因：

• 不同的属性顺序会产生不同的 SHA-256 哈希值
• 哈希不匹配会导致 ERR_INVALID_CONTENT_HASH 错误
• 服务会验证 JWT contentSha256 是否与请求正文的 SHA-256 匹配

故障排除

常见问题

1. 身份验证失败（ERR_INVALID_SIGNATURE）

   • 根本原因：在 payware 注册的公钥与您的私钥不匹配
   • 解决方案：确保在 payware 网站注册的公钥与您的私钥对应
   • 验证方法：使用 openssl rsa -in privateKey.pem -pubout 从私钥中提取公钥
   • 状态：✅ 已解决——必须在 payware 合作伙伴门户中正确注册密钥

2. 内容哈希不匹配错误（ERR_INVALID_CONTENT_HASH）

   • 根本原因：JSON 属性顺序不一致
   • 解决方案：使用确定性 JSON 序列化（此服务已实现）
   • 症状：服务日志显示预期的 SHA-256 哈希值与实际值不同
   • 预防方法：始终使用 /src/core/utils/json-serializer.js 中的 createMinimizedJSON()
   • 状态：✅ 已修复——已实现确定性 JSON 序列化

3. 创建交易失败

   • 确保提供了所有必需参数
   • 检查金额是否为非负数
   • 确认支持该交易类型
   • 状态：✅ 正常运行——已确认创建和取消操作均可正常使用

4. MCP 连接问题

   • 确保使用 npm start 启动服务
   • 检查 MCP 客户端是否已正确配置
   • 确认没有防火墙阻止 stdio 通信
   • 注意：使用 MCP Inspector（npm run inspector）进行调试

代理和桥接工具

HTTP 代理服务（npm run proxy）：

• 将 MCP 工具桥接至 HTTP REST API
• 适用于通过 HTTP 请求测试工具
• 文档：README-proxy.md

MCP 桥接（npm run bridge）：

• 将 MCP 服务连接至 MCP Inspector
• 对调试和开发至关重要
• 与 npm run inspector 配合使用

测试状态

✅ 已确认正常运行的操作：

• 使用 RS256 算法创建 JWT 令牌
• 创建交易（POST /api/transactions）
• 取消交易（PATCH /api/transactions/{id}）
• 用于确保 SHA-256 一致性的确定性 JSON 序列化
• 公钥/私钥对验证

🧪 测试结果：

• 所有 MCP 工具均已通过真实 payware 沙盒 API 测试
• 创建和取消交易的流程均已端到端验证可用
• 通过正确注册密钥，已解决签名验证问题

支持

如遇到以下问题：

• MCP 服务：检查服务日志和 MCP 客户端配置
• payware API：参阅 payware 文档并查看沙盒状态
• 集成：使用提供的代码示例和格式化工具
• 密钥问题：确保公钥已在 payware 合作伙伴门户中注册

许可证

MIT 许可证