# OPSG MCP Server

A local [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for the **OPSG (legacy iPay88) payment gateway**. It lets AI agents (Claude Desktop, Claude Code, Cursor, and any other MCP client) help you operate against the OPSG SOAP and JSON APIs using your own merchant credentials.

The server runs **locally on your machine** (stdio transport). Your Merchant Key never leaves your computer except inside signed requests sent directly to the gateway.

> ⚠️ **OPSG has NO sandbox.** Both environments (`payment.ipay88.com.my` and `node1.ipay88.com.my`) are **live** gateways. Capture, void, refund, and payment tools move real money. Money-moving tools are marked destructive so AI clients ask for confirmation, and refunds are disabled unless explicitly enabled.

## Features

**Transaction management** (SOAP / JSON APIs):

| Tool | Endpoint | Purpose |
|------|----------|---------|
| `opsg_requery_transaction` | `TxDetailsInquiry.asmx` | Transaction status + details (Version 5, no signature) |
| `opsg_capture` | `capture.asmx` | Capture (settle) a pre-auth — returns parsed response fields |
| `opsg_void_auth` | `VoidAuth.asmx` | Void an uncaptured authorization |
| `opsg_bank_void` | `VoidFunction.asmx` | Bank VOID API, Versions 1.0–4.0 (V4 uses CaptureId) |
| `opsg_refund` | `RefundRequestv2` (JSON) | Refund a transaction (**disabled by default** — see below) |
| `opsg_unbind_card` | `unbindcard.asmx` | Delete a stored card token |

**Payment initiation** (SOAP — real charges):

| Tool | Purpose |
|------|---------|
| `opsg_mh_gateway_payment` | Merchant Hosted card sale / bind / token charge via `GatewayService.svc` |
| `opsg_retail_payment` | Retail e-wallet: User Scan (QR generation) or Merchant Scan (barcode) |

**Integration helpers** (no network):

| Tool | Purpose |
|------|---------|
| `opsg_generate_hosted_checkout` | Signed auto-submit HTML form for `/epayment/entry.asp` |
| `opsg_generate_tokenization_payload` | Signed payload for `/epayment/entry_v2.asp` (BT / SC / UC / CCC) |
| `opsg_generate_signature` | Compute/debug the signature for any of the 9 flows |

**Reference lookups** (offline): `opsg_lookup_payment_ids` (hosted + retail QR/Scan PaymentIds), `opsg_flow_reference` (endpoints, transports, signature algorithms).

## Prerequisites

- Node.js 18+
- OPSG/iPay88 Merchant Code and Merchant Key

## Installation

```bash
git clone https://github.com/fredericktvf/opsg-mcp-server.git
cd opsg-mcp-server
npm install
npm run build
```

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `OPSG_MERCHANT_CODE` | ✓ | – | Your merchant code |
| `OPSG_MERCHANT_KEY` | ✓ | – | Your merchant key (keep secret) |
| `OPSG_ENVIRONMENT` | – | `production` | `production` (payment.ipay88.com.my) or `node1` (node1.ipay88.com.my) — **both LIVE** |
| `OPSG_ENABLE_REFUNDS` | – | `false` | Set `true` to expose `opsg_refund` |
| `OPSG_TOOLS` | – | `all` | Comma-separated tool whitelist (least privilege) |
| `OPSG_TIMEOUT` | – | `60000` | Gateway request timeout (ms) |

### Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "opsg": {
      "command": "node",
      "args": ["/path/to/opsg-mcp-server/dist/index.js"],
      "env": {
        "OPSG_MERCHANT_CODE": "M00000",
        "OPSG_MERCHANT_KEY": "<<YOUR_MERCHANT_KEY>>",
        "OPSG_ENVIRONMENT": "production",
        "OPSG_ENABLE_REFUNDS": "false",
        "OPSG_TOOLS": "all",

        "NODE_OPTIONS": "--dns-result-order=ipv4first",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}
```

The last two `env` entries are **OPTIONAL** — network workarounds, only needed if gateway calls fail with "fetch failed" while the gateway works in your browser:

- `NODE_OPTIONS: --dns-result-order=ipv4first` *(optional)* — fixes IPv6-preference failures, the most common cause on Windows.
- `NODE_TLS_REJECT_UNAUTHORIZED: "0"` *(optional)* — accepts a corporate proxy's self-signed certificate when TLS inspection is in place. ⚠️ Disables TLS certificate validation for this process; prefer `NODE_EXTRA_CA_CERTS` with your proxy's CA certificate where possible.

Remove them if you don't need them. Fully restart your MCP client after any config change.

### Recommended read-only production config

```json
"OPSG_TOOLS": "opsg_requery_transaction,opsg_generate_signature,opsg_lookup_payment_ids,opsg_flow_reference"
```

## Signature formulas (reference)

Amounts are stripped of dots/commas before signing (`1.00` → `100`).

| Flow | Algorithm | Base string |
|------|-----------|-------------|
| Hosted payment (entry.asp) | HMAC-SHA512 | Key + Code + RefNo + Amount + Currency + Xfield1 + PromoCode |
| Tokenization BT | HMAC-SHA512 | Key + Code + RefNo + CCNo + CCMonth + CCYear + CCCVV + Amount + Currency |
| Tokenization SC/UC | HMAC-SHA512 | Key + Code + RefNo + TokenId + Amount + Currency (+ Plan for SC) |
| Tokenization CCC | HMAC-SHA512 | Key + Code + RefNo + TokenId + Amount + Currency + MidPAN |
| MH Gateway (sales) | SHA256 | Key + Code + RefNo + CCNo + CCMonth + CCYear + CVV2 + Amount + Currency + Xfield1 |
| MH Gateway (SC) | SHA256 | Key + Code + RefNo + TokenId + Amount + Currency + Xfield1 |
| Retail e-wallet | HMAC-SHA512 | Key + Code + RefNo + Amount + Currency + xField1 + BarcodeNo + TerminalID |
| Capture | HMAC-SHA512 | Key + Code + TransId + Amount + Currency |
| Void Auth | SHA256 | Key + Code + TransId + Amount + Currency |
| Refund | SHA256 | **Code + Key** + TransId + RefundAmount + PayeeACNo |
| Unbind Card | HMAC-SHA512 | Code + Key + TokenID |
| Bank Void V1–V4 | HMAC-SHA512 | Key + Code + (CCTransId \| CaptureId for V4) + Amount + Currency |

Note the two easy-to-miss quirks: **Refund and Unbind Card put MerchantCode before MerchantKey**, and MH Gateway / Refund / Void Auth use **plain SHA256** while everything else uses HMAC-SHA512.

## Security notes

- **No sandbox exists.** Treat every call as production. Use small amounts and real transaction IDs you intend to act on.
- **Refunds are opt-in** (`OPSG_ENABLE_REFUNDS=true`). Capture, voids, unbind, and payment tools are always destructive-flagged so MCP clients prompt for confirmation.
- **Tool whitelisting** via `OPSG_TOOLS` — expose only what you need.
- **Merchant key masking** — debug base strings mask your key.
- **Card data** — MH Gateway and BT/CCC tokenization flows carry PANs; PCI DSS applies.

## Troubleshooting

**"Unable to reach OPSG gateway: fetch failed"** — add the optional `NODE_OPTIONS` / `NODE_TLS_REJECT_UNAUTHORIZED` entries shown in the configuration section, then fully restart your MCP client. The error message includes a `[cause: ...]` detail naming the exact network failure.

**Retail payment rejected / wrong XML structure** — the gateway requires the exact envelope this server builds: `mob:requestModelObj` root, `mhp:` field prefixes, lowercase `mhp:lang`, explicit `SignatureType`, and `BackendURL` included. If a payload appears with `a:` prefixes or a `<request>` root, it was hand-crafted by the AI client instead of calling `opsg_retail_payment` — always use the tool.

**Void fails signature/validation** — voids must reference the ORIGINAL transaction (CCTransId, or CaptureId for Bank Void V4) with the ORIGINAL full transaction amount. Partial voids are not supported. Requery first if unsure of the exact amount.

**Config changes don't take effect** — MCP servers launch once at client startup. Fully quit the app (Windows: system tray → right-click → Quit), then relaunch.

## Development

```bash
npm run dev      # run from source with tsx
npm run build    # compile to dist/
npx @modelcontextprotocol/inspector node dist/index.js
```

## Support

Refer to the OPSG Developer Portal (`/developer/simulator/opsg/`) for the interactive API console and reference.