OPSG 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):

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

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

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

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

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.