Lfwin Payment Mcp

LFWin Payment MCP Server

LFWin Payment MCP Server は、AI エージェント向けの決済機能サービスです。標準の MCP プロトコルを通じて、決済注文の作成、決済状況の照会、返金の開始、返金状況の照会などの機能を Cursor、Cline、Claude Desktop、企業向け AI アシスタント、自社開発のエージェントアプリに提供します。

プロジェクトでは、次の 2 種類の実装を提供しています。

• Node.js 版：node-mcp にあります。通常の MCP ユーザーには、npx で素早く起動する方法を推奨します。
• Python 版：payment_mcp にあります。既存の Python 環境をお持ちのユーザーや、二次開発を行うユーザーに適しています。

どちらの実装も、同じ MCP ツール機能を提供します。決済権限またはキーの取得については、サービスプロバイダーのカスタマーサポートにお問い合わせください。

機能

• create_payment_order：統一決済ページの決済注文を作成します
• query_payment_order：決済注文の状況を照会します
• refund_payment_order：返金を開始します
• query_refund_status：返金状況を照会します

決済注文を作成すると、決済リンクと QR コード関連のフィールドが返されます。

• pay_url：統一決済ページに移動するためのリンク
• qrcode：pay_url と同じです。スキャン用のコンテンツを必要とする呼び出し元との互換性を保つために使用します
• pay_qrcode_image：pay_url から生成された QR コード PNG data:image/png;base64,...
• pay_qrcode_base64：同じ QR コード PNG のプレーンな base64。data:image/png;base64, プレフィックスは含みません
• pay_qrcode_mime_type：常に image/png です。MCP の画像コンテンツブロックや自社開発クライアントでのレンダリングに使用します
• pay_qrcode_markdown：そのまま表示できる Markdown 画像テキスト
• payment_display_examples：Markdown、HTML/img、MCP image content、決済リンクへのフォールバックなどのケースに応じた表示例

Node.js 版では、MCP ツールの結果に type: "image" の PNG コンテンツブロックも追加で返されるため、画像レンダリングに対応した MCP クライアントで QR コードをそのまま表示できます。

AI エージェントの使用ルール

注文後の QR コード表示

create_payment_order の呼び出しが成功すると、統一決済ページインターフェースの元の戻り値にある data は、決済ページへの URL または決済パラメーターを表します。data は文字列の場合もあれば、payUrl、url、qrcode、code_url などのフィールドを含むオブジェクトの場合もあります。この MCP サービスは、オブジェクトが誤って [object Object] として表示されないよう、これを文字列の pay_url に標準化し、あわせて QR コードのフィールドも提供します。AI エージェントは、クライアントの機能に応じて表示方法を選択してください。

• Markdown に対応したチャットウィンドウ：pay_qrcode_markdown を直接出力する方法を優先してください。
• MCP 画像コンテンツブロックに対応したクライアント：Node.js 版のツール結果には type: "image" の PNG コンテンツブロックが含まれるため、そのまま表示できます。
• フロントエンドで画像を独自にレンダリングする場合：完全な data:image/png;base64,... データ URL である pay_qrcode_image を使用してください。<img src> にそのまま指定できます。
• プレーンな base64 のみ受け付けるクライアント：pay_qrcode_base64 を使用し、メディアタイプを pay_qrcode_mime_type に設定してください。
• 決済ページへの移動、または QR コードの独自生成が必要な場合：pay_url を使用してください。qrcode は pay_url と同じで、互換性のためのフィールドにすぎません。

QR コードや決済リンクを表示せずに、「注文が作成されました」とだけユーザーに伝えないでください。ユーザー向けには QR コードを表示し、スキャンに失敗した場合の代替リンクとして pay_url も残してください。

決済フィールドの表示例

create_payment_order の戻り値が order に保存されているとします。

Markdown チャットウィンドウでは、そのまま出力できます。

{order.pay_qrcode_markdown}

Web フロントエンドでは、完全なデータ URL を画像タグに指定できます。

<img alt="Payment QR Code" src="{order.pay_qrcode_image}" />

React/Vue などのフロントエンドでは、画像アドレスをそのままバインドできます。

<img alt="Payment QR Code" src={order.pay_qrcode_image} />

MCP または自社開発クライアントが画像コンテンツブロックのみを受け付ける場合は、プレーンな base64 と MIME を使用してください。

{
  "type": "image",
  "mimeType": "image/png",
  "data": "{order.pay_qrcode_base64}"
}

画像を表示できない場合は、代替の決済リンクを必ず表示してください。

[点击打开支付链接]({order.pay_url})

クライアントが QR コードを独自に生成する必要がある場合は、QR コードのコンテンツとして qrcode または pay_url を使用してください。pay_qrcode_image をテキストとして再び QR コードにエンコードしないでください。

注文番号の使用ルール

merchant_order_no、order_no、order_time はそれぞれ異なる値です。

• merchant_order_no：加盟店注文番号です。注文の作成時に渡します。インターフェースドキュメントの mch_orderid に対応し、加盟店システム内での関連付けと表示に使用します。
• order_no：プラットフォーム注文番号です。決済プラットフォームから返されます。インターフェースドキュメントの orderid に対応し、この MCP サービスでの注文照会、返金、返金照会に使用します。
• order_time：この MCP が決済注文を作成した際に記録した注文時刻です。形式は yyyyMMddHHmmss です。統一決済ページの pre_order がプラットフォームの orderid を返さなかった場合、後続の決済状況のポーリングでは merchant_order_no + order_time を必ず使用してください。

AI エージェントは、create_payment_order の戻り値に含まれる order_no、merchant_order_no、order_time を保存する必要があります。

• order_no_available=true かつ order_no が空でない場合、後続の query_payment_order、refund_payment_order、query_refund_status の呼び出しでは、order_no を優先して使用してください。
• order_no_available=false または order_no=null の場合、merchant_order_no を order_no として使用しないでください。決済状況をポーリングするには、query_payment_order を呼び出し、注文の作成時に返された merchant_order_no と order_time を渡してください。
• 返金関連のツールでは、引き続きプラットフォームの order_no/orderid が必要です。注文の作成時にプラットフォーム注文番号が返されなかった場合は、返金または返金照会を開始する前に、まず決済照会でプラットフォームの orderid を取得してください。

クエリと返金ステータスの判定

• 支払いの照会：order_no を優先して渡してください。注文の作成時に order_no が空の場合は、merchant_order_no と order_time を渡してください。status=10000 かつ paystatus=1 の場合は支払い成功、paystatus=0 の場合は支払い待ち、paystatus=2 の場合は支払い失敗を示します。merchant_order_no + order_time で照会したとき、ユーザーがまだQRコードをスキャンしていない、または支払いリンクを開いていない場合、プラットフォーム側の支払い注文がまだ作成されておらず、基盤インターフェースが raw_status=3040 / raw_message=订单号不存在 を返すことがあります。この MCP はこれを status=PENDING に標準化し、pending_reason=WAITING_FOR_USER_SCAN_OR_PAYMENT_ORDER_CREATION を返します。
• 返金の開始：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 のマークが付いています。

インストール方法 1：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 を参照してください。

インストール方法 2：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 に対応します。統一レジからプラットフォーム注文番号が返されなかった場合、このフィールドは null になります。
• order_no_available：プラットフォーム注文番号を取得できたかどうかを示します。
• merchant_order_no：加盟店注文番号。注文の作成時に渡した merchant_order_no / インターフェースのドキュメントにある mch_orderid に対応します。
• order_time：注文日時。形式は yyyyMMddHHmmss です。order_no が null の場合、支払い状況のポーリングには merchant_order_no + order_time を使用します。
• pay_url / qrcode / pay_qrcode_image / pay_qrcode_base64 / pay_qrcode_mime_type / pay_qrcode_markdown / payment_display_examples：支払い表示用のフィールドです。戻り値の pay_qrcode_markdown は、AI からユーザーにそのまま出力してQRコード決済に使用できます。pay_qrcode_image は <img src> として直接使用できます。pay_qrcode_base64 と pay_qrcode_mime_type の組み合わせは、MCP の画像コンテンツブロックや、base64 文字列のみを受け付けるクライアントで使用できます。

query_payment_order

支払い注文のステータスを照会します。

パラメーター：

• order_no：プラットフォーム注文番号。create_payment_order が返す order_no / インターフェースのドキュメントにある orderid です。このフィールドがある場合は優先して使用します。
• merchant_order_no：加盟店注文番号。省略可能です。order_no が空の場合は、order_time と一緒に渡す必要があります。
• order_time：注文日時。省略可能です。order_no が空の場合は、merchant_order_no と一緒に渡す必要があります。create_payment_order が返す order_time を使用してください。

merchant_order_no + order_time で照会し、ユーザーがまだQRコードをスキャンしていない場合、raw_status=3040 が返されるのは正常な支払い待ち／データベース反映待ちの状態です。この MCP は status=PENDING を返します。フロントエンドでは支払い待ちの状態を表示し、支払い失敗を通知するのではなく、引き続きポーリングしてください。

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.10
git push origin v0.1.10

v* タグをプッシュすると、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.10.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安装后，可选择启用哪些能力

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

发起支付：

发起退款：