mcp-newebpay 0.1.0

MCP Server for NewebPay (藍新金流) — AI-callable payment tools via Model Context Protocol

MCP NewebPay

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

繁體中文

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
• 信用卡定期定額串接技術手冊 NDNP v1.0.7

License

MIT License — see 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.