LFWin 支付 MCP Server - AI原生支付网关（收银台/退款/查单）

LFWin Payment MCP Server

LFWin Payment MCP Server 是一个面向 AI Agent 的支付能力服务。它通过标准 MCP 协议，把创建支付订单、查询支付状态、发起退款、查询退款状态等能力开放给 Cursor、Cline、Claude Desktop、企业智能助手和自研 Agent 应用。

项目同时提供两种实现：

• Node.js 版：位于 node-mcp，推荐普通 MCP 用户通过 npx 快速启动。
• Python 版：位于 payment_mcp，适合已有 Python 环境或需要二次开发的用户。

两种实现提供相同的 MCP 工具能力。获取支付权限或密钥，请联系服务商客服。

功能

• create_payment_order：创建统一收银台支付订单
• query_payment_order：查询支付订单状态
• refund_payment_order：发起退款
• query_refund_status：查询退款状态

创建支付订单时会返回支付链接和二维码相关字段：

• pay_url：统一收银台支付跳转链接
• qrcode：同 pay_url，用于兼容需要扫码内容的调用方
• pay_qrcode_image：基于 pay_url 生成的二维码 PNG data:image/png;base64,...
• pay_qrcode_markdown：可直接展示的 Markdown 图片文本

Node.js 版还会在 MCP 工具结果中额外返回 type: "image" 的 PNG 内容块，方便支持图片渲染的 MCP 客户端直接显示二维码。

AI Agent 使用规则

下单后的二维码展示

create_payment_order 调用成功后，统一收银台接口原始返回中的 data 表示支付跳转 URL 或支付参数。本 MCP 服务会把它标准化为 pay_url，并同时提供二维码字段。AI Agent 应按客户端能力选择展示方式：

• 支持 Markdown 的对话窗口：优先直接输出 pay_qrcode_markdown。
• 支持 MCP 图片内容块的客户端：Node.js 版工具结果里会带 type: "image" 的 PNG 内容块，可直接展示。
• 需要前端自行渲染图片：使用 pay_qrcode_image，这是 data:image/png;base64,... 格式。
• 需要跳转支付或自行生成二维码：使用 pay_url；qrcode 与 pay_url 相同，仅作为兼容字段。

不要只告诉用户“已创建订单”而不展示二维码或支付链接。面向用户时应展示二维码，并保留 pay_url 作为扫码失败时的备用链接。

订单号使用规则

merchant_order_no 和 order_no 不是同一个编号：

• merchant_order_no：商户订单号，创建订单时传入，对应接口文档里的 mch_orderid，用于商户系统内部关联和展示。
• order_no：平台订单号，由支付平台返回，对应接口文档里的 orderid，用于本 MCP 服务的订单查询、退款和退款查询。

AI Agent 必须保存 create_payment_order 返回的 order_no。后续调用 query_payment_order、refund_payment_order、query_refund_status 时，优先且默认使用这个 order_no，不要把创建订单时传入的 merchant_order_no 当作 order_no 使用。

接口文档说明底层订单查询接口也支持 mch_orderid，但当只传商户订单号时必须同时传 order_time 才能定位订单。本 MCP 当前的 query_payment_order(order_no) 参数语义是平台订单号，因此不应传 merchant_order_no。

查询和退款状态判断

• 支付查询：query_payment_order 的 order_no 必须传平台订单号。返回 status=10000 且 paystatus=1 表示支付成功；paystatus=0 表示待付款；paystatus=2 表示支付失败。
• 发起退款：refund_payment_order 的 order_no 必须传平台订单号，mch_refund_no 是商户退款流水号。同一笔订单多次部分退款时，每次退款应使用不同的 mch_refund_no。
• 退款不是发起即成功：退款请求返回 status=4001 或 status=10000 只表示请求已被接受或处理中，不代表退款成功。必须继续调用 query_refund_status 查询实际结果。
• 退款查询：query_refund_status 的 order_no 必须传平台订单号；如果发起退款时传了 mch_refund_no，查询时也应带上同一个 mch_refund_no。返回 status=4001 表示处理中；status=10000 且 refund_status=1 表示退款成功；status=10000 且 refund_status=2 表示退款失败。

环境变量

正常使用只需要配置：

PAYMENT_API_KEY=your_api_key_here
PAYMENT_SIGN_KEY=your_sign_key_here

默认配置：

• 接口域名：https://api2.lfwin.com
• 签名方式：MD5

通常不需要额外配置接口域名和签名方式。

PAYMENT_SIGN_KEY 只在 MCP Server 本地生成请求签名时使用，不会作为请求字段发送到 LFWin 接口，也不会出现在 MCP 工具返回结果中。通过 MCPB、Glama 等支持敏感字段的安装方式配置时，该字段已标记为 sensitive。

安装方式一：Node.js 版

推荐普通用户使用 Node.js 版。发布到 npm 后，可直接通过 npx 启动：

npx -y @litsen/lfwin-payment-mcp

Cursor 配置示例：

{
  "mcpServers": {
    "payment-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@litsen/lfwin-payment-mcp"],
      "env": {
        "PAYMENT_API_KEY": "your_api_key_here",
        "PAYMENT_SIGN_KEY": "your_sign_key_here"
      }
    }
  }
}

本地源码调试 Node.js 版：

cd node-mcp
npm install
npm run build
node dist/index.js

更多说明见 node-mcp/README.md。

安装方式二：Python 版

如果你已有 Python 3.12 或更高版本，也可以使用 Python 版。

从 GitHub 安装：

pip install git+https://github.com/litsen/lfwin-payment-mcp.git

安装完成后会得到 MCP 启动命令：

payment-mcp

Cursor 配置示例：

{
  "mcpServers": {
    "payment-mcp": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "payment-mcp"],
      "env": {
        "PAYMENT_API_KEY": "your_api_key_here",
        "PAYMENT_SIGN_KEY": "your_sign_key_here"
      }
    }
  }
}

源码开发时也可以这样运行：

pip install -r requirements.txt
python -m payment_mcp.mcp_stdio

Cline 配置

Node.js 版：

{
  "mcpServers": {
    "payment-mcp": {
      "command": "npx",
      "args": ["-y", "@litsen/lfwin-payment-mcp"],
      "env": {
        "PAYMENT_API_KEY": "your_api_key_here",
        "PAYMENT_SIGN_KEY": "your_sign_key_here"
      },
      "disabled": false
    }
  }
}

Python 版：

{
  "mcpServers": {
    "payment-mcp": {
      "command": "cmd",
      "args": ["/c", "payment-mcp"],
      "env": {
        "PAYMENT_API_KEY": "your_api_key_here",
        "PAYMENT_SIGN_KEY": "your_sign_key_here"
      },
      "disabled": false
    }
  }
}

工具参数

create_payment_order

创建支付订单。

参数：

• merchant_order_no：商户订单号，必须唯一
• amount：支付金额，单位为元
• notify_url：异步通知地址，可选

返回结果：

• order_no：平台订单号，对应接口文档里的 orderid。后续查询、退款、退款查询必须优先使用该值。
• merchant_order_no：商户订单号，对应创建订单时传入的 merchant_order_no / 接口文档里的 mch_orderid，不要用它替代 order_no 查询。
• pay_url / qrcode / pay_qrcode_image / pay_qrcode_markdown：支付展示字段。返回结果中的 pay_qrcode_markdown 可以直接让 AI 输出给用户，用于扫码支付。

query_payment_order

查询支付订单状态。

参数：

• order_no：平台订单号，即 create_payment_order 返回的 order_no / 接口文档里的 orderid。不要传 merchant_order_no。

refund_payment_order

发起退款。

参数：

• order_no：平台订单号，即 create_payment_order 返回的 order_no / 接口文档里的 orderid。不要传 merchant_order_no。
• refund_amount：退款金额，单位为元
• reason：退款原因
• mch_refund_no：商户退款流水号，必须唯一。同一订单多次部分退款时，每次使用不同值。

退款请求返回 status=4001 或 status=10000 只表示请求已被接受或处理中，不代表退款成功。必须继续调用 query_refund_status。

query_refund_status

查询退款状态。

参数：

• order_no：平台订单号，即 create_payment_order 返回的 order_no / 接口文档里的 orderid。不要传 merchant_order_no。
• mch_refund_no：商户退款流水号，可选；如果发起退款时传入了该值，查询时应使用同一个值定位退款记录。

状态判断：

• status=4001：退款处理中，需要稍后再次查询。
• status=10000 且 refund_status=1：退款成功。
• status=10000 且 refund_status=2：退款失败。

Open Plugins / Cursor Directory

仓库根目录提供 mcp.json，用于 Open Plugins / Cursor Directory 识别 MCP 组件。

Glama

仓库根目录提供 glama.json、Dockerfile、LICENSE、SECURITY.md 和 GitHub Actions CI，用于提升 Glama 收录和评分。

发布

Python 版构建 wheel 包：

pip install build
python -m build

Node.js 版发布 npm 包：

cd node-mcp
npm login
npm publish --access public

GitHub Release：

git tag v0.1.3
git push origin v0.1.3

推送 v* tag 后，Release workflow 会自动构建 .mcpb 并上传到 GitHub Release。

MCPB 打包

.mcpb 是一个包含本地 MCP Server 和 manifest.json 的 zip 包，适合 Claude Desktop 等支持 MCPB 的客户端一键安装。

本项目推荐用 Node.js 版打 MCPB，因为 Claude Desktop 在 macOS 和 Windows 上自带 Node 运行环境，用户不需要额外安装 Python。

先构建 Node.js 版：

cd node-mcp
npm install
npm run build

然后回到项目根目录执行：

.\scripts\build-mcpb.ps1

生成文件：

dist/lfwin-payment-mcp-0.1.3.mcpb

MCPB 安装时会提示用户填写：

• Payment API Key
• Payment Sign Key

这两个值会通过 mcpb/manifest.json 的 user_config 注入为 PAYMENT_API_KEY 和 PAYMENT_SIGN_KEY，不会写死在包里。其中 Payment Sign Key 已标记为敏感字段，只用于本地签名。

安全说明

• 不要把真实的 PAYMENT_API_KEY、PAYMENT_SIGN_KEY 提交到 GitHub。
• 建议通过环境变量、IDE Secret 或服务器密钥管理系统注入密钥。
• 本项目默认使用 stdio 方式作为本地 MCP 服务运行。
• 如果要部署成远程 MCP 服务，请自行增加认证、租户隔离、访问控制和 Origin 校验。

演示示例

Cursor安装后，可选择启用哪些能力

智能体调用时会自动生成对应的支付订单，可引导用户扫码完成支付

发起支付：

发起退款：