OPSG MCP Server

A local Model Context Protocol (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):

Payment initiation (SOAP — real charges):

Integration helpers (no network):

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

Related MCP server: Bayarcash MCP Server

Prerequisites

• Node.js 18+

• OPSG/iPay88 Merchant Code and Merchant Key

Installation

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

Configuration

Claude Desktop / Claude Code

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

"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).

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

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.