# Mcp Newebpay

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-asgard-ai-platform-mcp-newebpay`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [asgard-ai-platform](https://agentstack.voostack.com/s/asgard-ai-platform)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [asgard-ai-platform](https://github.com/asgard-ai-platform)
- **Source:** https://github.com/asgard-ai-platform/mcp-newebpay
- **Website:** https://pypi.org/project/mcp-newebpay/

## Install

```sh
agentstack add mcp-asgard-ai-platform-mcp-newebpay
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 (藍新金流)](https://www.newebpay.com/) — Taiwan's leading payment gateway. Exposes 8 payment APIs as AI-callable tools.

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

Part of the [Asgard AI Platform](https://github.com/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

```bash
pip install mcp-newebpay
```

### Or clone and install locally

```bash
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

```bash
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

```bash
python mcp_server.py
```

### Claude Code Integration

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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```bash
# 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](https://github.com/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](https://github.com/asgard-ai-platform)
- **Source:** [asgard-ai-platform/mcp-newebpay](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-asgard-ai-platform-mcp-newebpay
- Seller: https://agentstack.voostack.com/s/asgard-ai-platform
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.