Mcp Newebpay

MCP NewebPay

[](https://pypi.org/project/mcp-newebpay/) [](https://pypi.org/project/mcp-newebpay/) [](https://opensource.org/licenses/MIT) [](https://github.com/asgard-ai-platform/mcp-newebpay/releases) [](https://github.com/asgard-ai-platform/mcp-newebpay/actions/workflows/publish.yml) [](https://modelcontextprotocol.io/)

Model Context Protocol server for NewebPay (藍新金流) — Taiwan's leading payment gateway. Exposes 8 payment APIs as AI-callable tools.

[繁體中文](README.zh-TW.md)

Part of the Asgard AI Platform open-source ecosystem.

Features

• 8 payment tools covering payment creation, transaction queries, refunds, and recurring payment management
• AES-256-CBC encryption built-in — handles NewebPay's encryption/decryption protocol automatically
• Test/Production switch — single env var to toggle between sandbox and live environments
• stdio JSON-RPC 2.0 — standard MCP transport

Tools

Payment (NDNF — Online Transaction)

| Tool | API | Description | |------|-----|-------------| | create_mpg_payment | NPA-F01 | Create a payment and return encrypted form data for browser redirect | | query_trade | NPA-B02 | Query single transaction status, payment and refund details | | cancel_authorization | NPA-B01 | Cancel credit card authorization | | close_refund | NPA-B031~34 | Request close, refund, cancel close, or cancel refund | | ewallet_refund | NPA-B06 | Refund e-wallet payments (LINE Pay, Taiwan Pay, etc.) |

Recurring Payment (NDNP — Credit Card Periodic Payment)

| Tool | API | Description | |------|-----|-------------| | create_period_payment | NPA-B05 | Create a recurring mandate and return encrypted form data for browser redirect | | alter_period_status | NPA-B051 | Suspend, terminate, or restart a recurring mandate | | alter_period_content | NPA-B052 | Modify mandate amount, billing cycle, or expiry |

Quick Start

Install from PyPI

pip install mcp-newebpay

Or clone and install locally

git clone https://github.com/asgard-ai-platform/mcp-newebpay.git
cd mcp-newebpay
uv venv && source .venv/bin/activate
uv pip install -e .

Configure

cp .env.example .env
# Edit .env with your NewebPay credentials

Environment variables (configure only what you need):

| Variable | Description | |----------|-------------| | NEWEBPAY_ENV | test (default) or production | | NDNF — Online Transaction | | | NEWEBPAY_NDNF_MERCHANT_ID | Merchant ID for payment APIs | | NEWEBPAY_NDNF_HASH_KEY | Hash Key (32 chars) | | NEWEBPAY_NDNF_HASH_IV | Hash IV (16 chars) | | NDNP — Recurring Payment | | | NEWEBPAY_NDNP_MERCHANT_ID | Merchant ID for recurring APIs | | NEWEBPAY_NDNP_HASH_KEY | Hash Key (32 chars) | | NEWEBPAY_NDNP_HASH_IV | Hash IV (16 chars) |

> NDNF and NDNP may use different merchant accounts. Only configure the set you need — tools for unconfigured APIs will report a clear error if called.

Run

python mcp_server.py

Claude Code Integration

This project includes .mcp.json for auto-discovery. Add to your Claude Code config:

{
  "mcpServers": {
    "newebpay": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "/path/to/mcp-newebpay",
      "env": {
        "NEWEBPAY_ENV": "test",
        "NEWEBPAY_NDNF_MERCHANT_ID": "your_ndnf_merchant_id",
        "NEWEBPAY_NDNF_HASH_KEY": "your_ndnf_hash_key",
        "NEWEBPAY_NDNF_HASH_IV": "your_ndnf_hash_iv",
        "NEWEBPAY_NDNP_MERCHANT_ID": "your_ndnp_merchant_id",
        "NEWEBPAY_NDNP_HASH_KEY": "your_ndnp_hash_key",
        "NEWEBPAY_NDNP_HASH_IV": "your_ndnp_hash_iv"
      }
    }
  }
}

Usage Examples

Once the MCP server is running and connected to your AI assistant, you can interact with NewebPay using natural language:

Create Payment

You: "Help me create a credit card payment for order A20250403001, amount NT$350, item: Annual membership"

AI: I've generated the payment form for order A20250403001. Here are the details:

• Amount: NT$350
• Payment page URL: https://ccore.newebpay.com/MPG/mpg_gateway

Please open the following URL in a browser to complete the payment. The customer will be redirected to NewebPay's secure payment page to enter their card details.

Raw API Response

{
  "url": "https://ccore.newebpay.com/MPG/mpg_gateway",
  "form_data": {
    "MerchantID": "MS358668323",
    "TradeInfo": "04ac744434c76218dd6ba52b78da433f...",
    "TradeSha": "EFCFC9E418A8DCBE49370897FA4FCFFA...",
    "Version": "2.0"
  }
}

---

Query Transaction

You: "Has order mcp1775195782 been paid? The amount was NT$100"

AI: Yes, order mcp1775195782 has been paid successfully. Here's a summary:

| Item | Detail | |------|--------| | Status | Paid (TradeStatus: 1) | | Amount | NT$100 | | Payment Method | Credit Card (CREDIT) | | Card | 400022******1111 | | Auth Code | 114493 | | Acquiring Bank | KGI (凱基銀行) | | Close Status | Settled (3) | | Refund Status | None (0) | | Trade No | 26040313563142518 |

Raw API Response

{
  "Status": "SUCCESS",
  "Message": "查詢成功",
  "Result": {
    "MerchantID": "MS358668323",
    "Amt": 100,
    "TradeNo": "26040313563142518",
    "MerchantOrderNo": "mcp1775195782",
    "TradeStatus": "1",
    "PaymentType": "CREDIT",
    "RespondCode": "00",
    "Auth": "114493",
    "Card6No": "400022",
    "Card4No": "1111",
    "AuthBank": "KGI",
    "CloseStatus": "3",
    "BackStatus": "0"
  }
}

---

Close (Settle)

You: "Request a close for order demo1775199586, amount NT$200"

AI: Done! The close (settle) request for order demo1775199586 has been submitted successfully.

• Amount: NT$200
• Trade No: 26040315000942606
• The funds will be settled to your account on the next business cycle.

Raw API Response

{
  "Status": "SUCCESS",
  "Message": "請款資料新增成功_模擬信用卡請款成功",
  "Result": {
    "MerchantID": "MS358668323",
    "Amt": 200,
    "MerchantOrderNo": "demo1775199586",
    "TradeNo": "26040315000942606"
  }
}

---

Cancel Authorization

You: "Cancel the credit card authorization for order canc1775199618, amount NT$150"

AI: The credit card authorization for order canc1775199618 has been cancelled.

• Amount: NT$150
• Trade No: 26040315002642607
• The hold on the customer's credit card has been released.

Raw API Response

{
  "Status": "SUCCESS",
  "Message": "放棄授權成功",
  "Result": {
    "MerchantID": "MS358668323",
    "Amt": 150,
    "MerchantOrderNo": "canc1775199618",
    "TradeNo": "26040315002642607"
  }
}

---

Modify Recurring Payment

You: "Change the recurring amount to NT$149 for mandate P260403144725zl3MVV"

AI: The recurring mandate P260403144725zl3MVV has been updated:

• New amount per period: NT$149
• Next billing date: 2026-04-05
• The updated amount will take effect starting from the next billing cycle.

Raw API Response

{
  "Status": "SUCCESS",
  "Message": "定期定額委託單修改成功！",
  "Result": {
    "MerOrderNo": "per1775198836",
    "PeriodNo": "P260403144725zl3MVV",
    "AlterAmt": "149",
    "NewNextAmt": "149",
    "NewNextTime": "2026-04-05"
  }
}

---

Suspend Recurring Payment

You: "Pause the recurring mandate P260403144725zl3MVV"

AI: The recurring mandate P260403144725zl3MVV has been paused. No further charges will be made until you resume it.

To resume, just say: "Resume mandate P260403144725zl3MVV"

Raw API Response

{
  "Status": "SUCCESS",
  "Message": "定期定額委託單暫停成功",
  "Result": {
    "MerOrderNo": "per1775198836",
    "PeriodNo": "P260403144725zl3MVV",
    "AlterType": "suspend"
  }
}

Project Structure

mcp-newebpay/
├── app.py                       # MCPServer singleton
├── mcp_server.py                # Entry point (stdio transport)
├── config/settings.py           # Endpoints, URL builder, env switch
├── connectors/
│   └── newebpay_client.py       # AES encrypt/decrypt + Form POST
├── auth/
│   └── newebpay.py              # Merchant ID + Hash Key/IV credentials
├── tools/
│   ├── payment_tools.py         # NDNF: query, cancel, close/refund, e-wallet refund
│   └── periodic_tools.py        # NDNP: alter status, alter content
├── tests/test_all_tools.py      # E2E test runner
└── reference/                   # NewebPay official API docs (PDF)

Testing

# Test connection with NewebPay API
python scripts/auth/test_connection.py

# Run all tool E2E tests
python tests/test_all_tools.py

NewebPay API Reference

• [線上交易─幕前支付技術串接手冊 NDNF v1.2.1](reference/線上交易─幕前支付技術串接手冊_NDNF-1.2.1.pdf)
• [信用卡定期定額串接技術手冊 NDNP v1.0.7](reference/信用卡定期定額串接技術手冊_NDNP-1.0.7.pdf)

License

MIT License — see [LICENSE](LICENSE) for details.

Part of the Asgard Ecosystem

This server is part of the Asgard AI Platform, connecting AI to real-world services across e-commerce, finance, government data, and more.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: asgard-ai-platform
• Source: asgard-ai-platform/mcp-newebpay
• License: MIT
• Homepage: https://pypi.org/project/mcp-newebpay/

Install and usage instructions live in the source repository linked above.