oen-payment-mcp-server

  ___               ____                                  _  ⚡️⚡️
 / _ \  ___ _ __   |  _ \ __ _ _   _ _ __ ___   ___ _ __ | |_ ⚡️
| | | |/ _ \ '_ \  | |_) / _` | | | | '_ ` _ \ / _ \ '_ \| __|
| |_| |  __/ | | | |  __/ (_| | |_| | | | | | |  __/ | | | |_
 \___/ \___|_| |_| |_|   \__,_|\__, |_| |_| |_|\___|_| |_|\__|
                               |___/
 __  __  ____ ____    ____
|  \/  |/ ___|  _ \  / ___|  ___ _ ____   _____ _ __
| |\/| | |   | |_) | \___ \ / _ \ '__\ \ / / _ \ '__|
| |  | | |___|  __/   ___) |  __/ |   \ V /  __/ |
|_|  |_|\____|_|     |____/ \___|_|    \_/ \___|


 您的友善支付助手
 應援金流的 Model Context Protocol (MCP) 伺服器（內部預覽 2.0.0）

內部預覽，只連測試環境

目前只提供應援內部測試。程式鎖定只連測試環境（https://payment-api.testing.oen.tw），不會實際扣款；正式環境不開放，填入正式環境的 token 會被拒絕。

🍌 功能

💳 建立結帳頁：單次付款、每月定期定額、預約定期定額（可指定首期日與扣款間隔）
🔐 建立綁卡頁：消費者在應援的頁面完成 3D 驗證，token 經付款通知送到你的伺服器
📊 查詢：交易明細、交易列表、用訂單編號查詢、定期定額明細
🛑 取消定期定額
📋 內建開發者文件：文件站的快照，可以指定頁面讀取，不需要網路

🍌 使用方式

確認你的測試環境網域已開通金流與 API 串接，並在測試環境 CRM「API 串接設定」產生 API token 後，依下列方式擇一安裝：

本機安裝（各種 MCP 用戶端）
一鍵安裝（Claude Desktop）

🍌 本機安裝（各種 MCP 用戶端）

前置需求

Node.js 22.18 以上（建議用 nvm 管理 Node 版本）
下載 tarball（點我下載）

安裝步驟

# 安裝 MCP 套件（請依 tarball 的位置調整路徑）
npm install -g ./OEN-Tech-oen-payment-mcp-server-2.0.0.tgz

MCP 用戶端設定

Claude Code：

claude mcp add oen-payment -- oen-payment-mcp-server --merchantId=<網域代號> --token=<測試環境 API token>

其他用戶端，在設定檔加入：

{
  "mcpServers": {
    "oen-payment": {
      "command": "oen-payment-mcp-server",
      "args": [
        "--merchantId=<網域代號，例如 ming>",
        "--token=<測試環境 API token>"
      ]
    }
  }
}

網域代號：應援頁是 https://ming.testing.oen.tw 就填 ming。
不需要設定環境。舊設定裡的 --env=testing 仍可使用，其他值會拒絕啟動。
各家用戶端的設定方式略有不同，請參考下方「常見 MCP 設定文件」。

🍌 一鍵安裝（Claude Desktop）

前置需求

已安裝 Claude Desktop
下載 MCP Bundle（點我下載）。原本的 .dxt 格式已改名為 .mcpb。
若安裝後無法執行，請手動安裝 Node.js（22.18 以上）

安裝步驟

雙擊下載的 .mcpb 檔，會開啟 Claude Desktop
- 如果沒有開啟：打開 Claude Desktop → Settings → Extensions，把 .mcpb 檔拖進視窗
按「Install」
填入網域代號（merchantId）與測試環境的 API token

🍌 可用工具

工具	說明	注意事項
`checkout_link`	建立單次付款結帳頁（POST /checkout）	`productDetails` 必填，品項合計要等於 `amount`；結帳頁 5 分鐘內有效
`subscription_checkout`	建立每月扣款的定期定額結帳頁（POST /checkout-subscription）	消費者在結帳頁付款時才扣第一期；只支援信用卡
`scheduled_subscription_checkout`	建立可指定首期日與扣款間隔的預約定期定額結帳頁（POST /checkout-schedule）	回傳 `subscriptionHid`（S 開頭），查詢與取消都用它
`exchange_token_by_3d`	建立綁卡頁，消費者完成 3D 驗證後 token 經付款通知送達（POST /checkout-token）	綁卡頁 10 分鐘內有效；token 只會經付款通知送達
`get_transaction`	查詢交易明細（GET /transactions/:id）	建議用 27 字元的內部 id 查詢
`get_transactions`	查詢交易列表，包含網域全部款項（GET /transactions）	`start`、`end` 要一起帶
`get_transactions_by_order_id`	用訂單編號查詢所有交易（GET /order/:orderId/transactions）	結果不明或逾時時，先用它確認再決定要不要重建
`get_subscription`	查詢定期定額明細（GET /subscriptions/:id）	已扣完的狀態是 `done`
`cancel_subscription`	取消定期定額，取消後不能恢復（PUT /subscriptions/:subscriptionHid）	只接受 S 開頭的 17 字元編號
`read_oen_docs`	讀取內建的開發者文件（文件站快照，可用 page 指定頁面）	不帶 `page` 回傳索引，例如 `page: "api/checkout.md"`
`get_config`	查看目前設定（固定連測試環境，不回傳 token）	—

三個建立結帳頁的工具沒帶 successUrl、failureUrl 時，付款後會導回應援測試環境的預設結果頁（https://static-assets.testing.oen.tw/payment-default/checkout-success.html、checkout-failure.html）。
orderId 請帶你自己的訂單編號；省略時每次呼叫都會自動產生新的編號（MCP- 開頭）。
這個版本沒有退款、用 token 扣款與商店定期購列表的工具。

🍌 系統需求

Node.js 22.18 以上
測試環境網域已開通金流與 API 串接

🍌 文件

常見 MCP 設定文件

🍌 問題排除

設定後無法啟動：
- 確認已安裝 Node.js，而且版本是 22.18 以上
- 確認 merchantId 與 token 都有設定；merchantId 只能是網域代號（小寫英文、數字與 -）
- 錯誤訊息說「只能連測試環境」：移除設定裡 testing 以外的 --env 或 OEN_PAYMENT_ENV
- 錯誤訊息說「這是正式環境的 token」：改用測試環境 CRM 產生的 token
- Windows 使用者可以改在 WSL 執行，或用系統管理員權限開啟你的工具
MCP Server 沒出現在清單中：設定完成後重新啟動你的工具。
AI 沒有呼叫 MCP 工具：
- 試著把需求講得更明確，例如「用 checkout_link 建立一筆 500 元的結帳頁」
- 確認你的工具已啟用 Oen Payment MCP Server
工具有執行但回傳錯誤（結果會標 isError，並附上 API 的 code 與處理建議）：
- 401 A0001：token 錯誤，或 token 已被重新產生
- 400 V0001：參數錯誤，依 message 修正，例如 PRODUCT_AMOUNT_NOT_MATCH（品項合計不等於金額）、USER_NAME_AND_EMAIL_REQUIRED（網域開通電子發票時姓名與 Email 必填）
- 400 V0002：金流尚未開通，或目前狀態不能做這個動作
- 403（沒有 code）：測試環境沒有 IP 白名單，代表請求在進入 API 前就被網路上的代理或防火牆擋下
- 409 C026：付款結果不明，不要重試；先用 get_transactions_by_order_id 查詢
- 完整清單見錯誤碼一覽
AI 工具回應超出限制或訊息太長：確認 AI 工具的方案沒有超出用量，免費方案較容易遇到。也可以關掉用不到的工具，減少 token 消耗。

🍌 注意事項

這是內部預覽版，只連測試環境，請不要用在正式環境。
只把測試環境的 API token 交給 AI 工具，並妥善保管；不要貼在對話或 issue 裡。
避免安裝來路不明的 MCP Server。

Power by the Oen Team 🐵⚡️

oen-payment-mcp-server

🍌 功能

🍌 使用方式

🍌 本機安裝（各種 MCP 用戶端）

前置需求

安裝步驟

MCP 用戶端設定

🍌 一鍵安裝（Claude Desktop）

前置需求

安裝步驟

🍌 可用工具

🍌 系統需求

🍌 文件

相關文件

常見 MCP 設定文件

🍌 問題排除

🍌 注意事項