Metadata-Version: 2.4
Name: mcp-newebpay
Version: 0.1.0
Summary: MCP Server for NewebPay (藍新金流) — AI-callable payment tools via Model Context Protocol
Author-email: Asgard AI Platform <dev@asgard.ai>
License: MIT
Project-URL: Homepage, https://github.com/asgard-ai-platform/mcp-newebpay
Project-URL: Source, https://github.com/asgard-ai-platform/mcp-newebpay
Project-URL: Issues, https://github.com/asgard-ai-platform/mcp-newebpay/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pycryptodome>=3.20.0
Dynamic: license-file

# MCP NewebPay

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.

<details>
<summary>Raw API Response</summary>

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

---

### 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 |

<details>
<summary>Raw API Response</summary>

```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"
  }
}
```
</details>

---

### 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.

<details>
<summary>Raw API Response</summary>

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

---

### 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.

<details>
<summary>Raw API Response</summary>

```json
{
  "Status": "SUCCESS",
  "Message": "放棄授權成功",
  "Result": {
    "MerchantID": "MS358668323",
    "Amt": 150,
    "MerchantOrderNo": "canc1775199618",
    "TradeNo": "26040315002642607"
  }
}
```
</details>

---

### 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.

<details>
<summary>Raw API Response</summary>

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

---

### 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"*

<details>
<summary>Raw API Response</summary>

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

## 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.
