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.
- 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
| 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.) |
| 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 |
pip install mcp-newebpaygit clone https://github.com/asgard-ai-platform/mcp-newebpay.git
cd mcp-newebpay
uv venv && source .venv/bin/activate
uv pip install -e .cp .env.example .env
# Edit .env with your NewebPay credentialsEnvironment 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.
python mcp_server.pyThis 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"
}
}
}
}Once the MCP server is running and connected to your AI assistant, you can interact with NewebPay using natural language:
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"
}
}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"
}
}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"
}
}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"
}
}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"
}
}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"
}
}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)
# Test connection with NewebPay API
python scripts/auth/test_connection.py
# Run all tool E2E tests
python tests/test_all_tools.pyMIT License — see LICENSE for details.
This server is part of the Asgard AI Platform, connecting AI to real-world services across e-commerce, finance, government data, and more.