jazzcash-mcp

MCP server for the JazzCash payment gateway (Pakistan). Exposes Mobile Wallet payments, CNIC-enabled Mobile Account payments, Over-The-Counter (OTC) vouchers, status inquiry, and refunds as MCP tools. Requests are signed with JazzCash's HMAC-SHA256 secure hash, and responses are hash-verified.

Tools (5)

| Tool | Type | Description | |------|------|-------------| | create_payment | write | Mobile Wallet (MWALLET) payment | | create_mobile_account_payment | write | CNIC-enabled Mobile Account payment (MWALLET) | | create_voucher | write | Over-The-Counter (OTC) voucher — returns a voucher number redeemed offline at an outlet | | check_payment_status | read | Transaction status inquiry (PaymentInquiry/Inquire) | | refund_payment | write, destructive | Refund a transaction (authorize/Refund; card transactions per JazzCash) |

Quick Start

{
  "mcpServers": {
    "jazzcash": {
      "command": "npx",
      "args": ["-y", "@theyahia/jazzcash-mcp"],
      "env": {
        "JAZZCASH_MERCHANT_ID": "<YOUR_MERCHANT_ID>",
        "JAZZCASH_PASSWORD": "<YOUR_PASSWORD>",
        "JAZZCASH_INTEGRITY_SALT": "<YOUR_SALT>",
        "JAZZCASH_ENV": "sandbox"
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | JAZZCASH_MERCHANT_ID | Yes | — | Merchant ID from the JazzCash portal | | JAZZCASH_PASSWORD | Yes | — | Merchant password | | JAZZCASH_INTEGRITY_SALT | Yes | — | HMAC integrity salt (shared secret) | | JAZZCASH_ENV | No | sandbox | sandbox or production | | JAZZCASH_BASE_URL | No | — | Full base URL override (e.g. for staging); takes precedence over JAZZCASH_ENV |

The server fails fast at startup if the three required credentials are missing.

Amounts

All amount parameters are in PKR rupees (e.g. 5000 = 5000 PKR). The server converts to paisa (amount × 100, no decimal point) before signing, because JazzCash's pp_Amount is expressed in the lowest denomination. So 5000 is sent to JazzCash as pp_Amount=500000.

Sandbox vs Production

| Environment | Host | |-------------|------| | sandbox (default) | https://sandbox.jazzcash.com.pk/ApplicationAPI/API | | production | https://payments.jazzcash.com.pk/ApplicationAPI/API |

The default is sandbox for safety. Set JAZZCASH_ENV=production (or a full JAZZCASH_BASE_URL) to go live.

Verify endpoints against your merchant portal. JazzCash exposes the same operation under slightly different path/version conventions depending on the merchant-account generation, and the modern token-wallet endpoint differs from the documented Payment API. The endpoint paths in src/config.ts are best-evidence canonical values cross-checked against the official docs and multiple integrations; confirm the exact paths and whether pp_Version is expected against the per-merchant API URLs shown in your JazzCash merchant portal before transacting real money.

Security

• Request signing — every request carries an HMAC-SHA256 pp_SecureHash (integrity salt as both the prepended prefix and the HMAC key; empty fields excluded; lowercase hex). Verified against the official worked test vector in the test suite.
• Response verification — responses that include a pp_SecureHash are recomputed and compared (constant-time); a mismatch raises an error rather than returning unverified data.
• No secret leakage — pp_Password/pp_SecureHash are stripped from tool output, and upstream error bodies are never echoed back to the model (only redacted to stderr).

Demo Prompts

• "Create a JazzCash payment of 5000 PKR to 03001234567"
• "Check the status of transaction TXN-001"
• "Refund 3000 PKR for transaction TXN-001"
• "Create an OTC voucher for 2000 PKR for 03001234567 (CNIC 123456)"

Removed in 2.0 (and why)

2.0.0 removed three tools that targeted JazzCash endpoints which do not exist, verified against the official documentation and multiple independent integrations:

• get_balance — JazzCash has no balance-inquiry API.
• redeem_voucher — voucher redemption happens offline at a JazzCash outlet, not via a merchant API.
• inquire_transaction — duplicated check_payment_status; both now use the canonical PaymentInquiry/Inquire.

Other breaking changes: create_mobile_account_payment now uses the real MWALLET transaction type (there is no MA type), create_voucher now issues an OTC voucher, amounts are in rupees (auto-converted to paisa), and txn_ref is optional (auto-generated when omitted). See CHANGELOG.md.

Development

npm install
npm run build   # tsc → dist/
npm test        # vitest (schema, hash test-vector, response verification, fetch mocking)
npm run dev     # run from source via tsx

License

MIT