iyzico MCP Server

A Model Context Protocol server that gives AI agents a typed, safe interface to the iyzico payments API. Look up card BINs and installment plans, spin up hosted checkout forms, inspect payments, issue refunds and cancellations, and query recurring subscriptions — all from Claude Desktop, Claude Code, Cursor, or any MCP client.

iyzico is one of the most widely used payment gateways in Turkey. It exposes a rich REST API but signs every request with a non-trivial IYZWSv2 HMAC-SHA256 scheme; this server implements that correctly so you don't have to, and wraps each operation in a well-described, zod-validated tool.

Status: unofficial, community-built. Not affiliated with or endorsed by iyzico. Defaults to the sandbox environment so you can't accidentally move real money while experimenting.

---

Features

• 10 well-scoped tools covering BIN/installment lookups, checkout forms, payment inspection, refunds/cancellations, and subscription queries.
• Correct IYZWSv2 request signing (HMAC-SHA256), verified by a unit test against an independent reference implementation.
• Input validation with zod — malformed arguments are rejected before they ever reach iyzico.
• Graceful, informative errors. iyzico reports business failures as HTTP 200 with a status: "failure" body; this server surfaces those as real errors with the iyzico errorCode, so agents can react instead of proceeding on a silent failure.
• Sandbox-first & safe by default. Write operations (cancel_payment, refund_payment) are annotated as destructive so clients can warn the user.
• Runs over stdio — the standard transport for local MCP servers.

---

Requirements

• Node.js 18+ (uses the built-in global fetch).
• iyzico API credentials:
  • Sandbox: create a free merchant account at https://sandbox-merchant.iyzipay.com → Settings → API Keys.
  • Production: https://merchant.iyzipay.com → Settings → API Keys.

---

Installation

From source (current)

git clone <your-fork-url> iyzico-mcp
cd iyzico-mcp
npm install
npm run build

The built entrypoint is dist/index.js. You can run it directly:

IYZICO_API_KEY=sandbox-xxxx \
IYZICO_SECRET_KEY=sandbox-yyyy \
IYZICO_ENVIRONMENT=sandbox \
node dist/index.js

Via npx (once published)

If/after this package is published to npm, it can be launched without a local checkout:

npx -y iyzico-mcp

The config snippets below show both forms.

---

Configuration

All configuration is via environment variables:

Variable	Required	Default	Description
IYZICO_API_KEY	yes	—	Your iyzico API key.
IYZICO_SECRET_KEY	yes	—	Your iyzico secret key.
IYZICO_ENVIRONMENT	no	sandbox	sandbox (safe) or production (live money).
IYZICO_TIMEOUT_MS	no	30000	Per-request timeout in milliseconds.

Copy .env.example to .env for local reference. Credentials are read lazily, so the server will still start and list its tools without them — you'll only get an error (naming the missing variable) when you actually call a tool.

Verify your setup

# List the tools without any credentials (offline):
node dist/index.js --list-tools

# Confirm your credentials authenticate against iyzico:
#   then call the `ping` tool from your MCP client.

---

Client setup

Claude Desktop

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Using a local build:

{
  "mcpServers": {
    "iyzico": {
      "command": "node",
      "args": ["/absolute/path/to/iyzico-mcp/dist/index.js"],
      "env": {
        "IYZICO_API_KEY": "sandbox-xxxx",
        "IYZICO_SECRET_KEY": "sandbox-yyyy",
        "IYZICO_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Using npx (once published):

{
  "mcpServers": {
    "iyzico": {
      "command": "npx",
      "args": ["-y", "iyzico-mcp"],
      "env": {
        "IYZICO_API_KEY": "sandbox-xxxx",
        "IYZICO_SECRET_KEY": "sandbox-yyyy",
        "IYZICO_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Restart Claude Desktop after editing.

Claude Code

Add the server with the claude mcp add command:

# Local build:
claude mcp add iyzico \
  --env IYZICO_API_KEY=sandbox-xxxx \
  --env IYZICO_SECRET_KEY=sandbox-yyyy \
  --env IYZICO_ENVIRONMENT=sandbox \
  -- node /absolute/path/to/iyzico-mcp/dist/index.js

# npx (once published):
claude mcp add iyzico \
  --env IYZICO_API_KEY=sandbox-xxxx \
  --env IYZICO_SECRET_KEY=sandbox-yyyy \
  --env IYZICO_ENVIRONMENT=sandbox \
  -- npx -y iyzico-mcp

Or add it to .mcp.json in your project root:

{
  "mcpServers": {
    "iyzico": {
      "command": "node",
      "args": ["/absolute/path/to/iyzico-mcp/dist/index.js"],
      "env": {
        "IYZICO_API_KEY": "sandbox-xxxx",
        "IYZICO_SECRET_KEY": "sandbox-yyyy",
        "IYZICO_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project) using the same JSON shape as the Claude Desktop example above.

---

Tools

Tool	Type	What it does
ping	read-only	Verify connectivity and that your credentials authenticate.
check_bin	read-only	Look up bank/scheme/type metadata for a card BIN (first 6-8 digits).
retrieve_installment_info	read-only	Get installment plans and per-installment pricing for a BIN + amount.
initialize_checkout_form	write	Start a hosted checkout form; returns a payment page URL and token.
retrieve_checkout_form_result	read-only	Fetch the outcome of a checkout form by its token.
retrieve_payment	read-only	Get full detail of a payment (status, amounts, item transactions).
cancel_payment	write	Void a payment in full (same-day, before settlement).
refund_payment	write	Refund a payment transaction, in full or in part.
search_subscriptions	read-only	List/filter recurring subscriptions with paging.
retrieve_subscription	read-only	Get detail of one subscription by its reference code.

Write tools are annotated as destructive (readOnlyHint: false, destructiveHint: true) so MCP clients can prompt for confirmation.

Example prompts

Once connected, you can ask your agent things like:

• "Check the BIN 554960 and tell me which bank issued it and whether it's a credit or debit card." → check_bin
• "For a 1,200 TRY purchase on BIN 552879, what installment options are available and what's the total cost at 6 installments?" → retrieve_installment_info
• "Create a checkout form for a 249.90 TRY order for buyer Ada Lovelace, one virtual item, callback to https://example.com/iyzico/callback." → initialize_checkout_form
• "Look up payment 12345678 and refund the first basket item in full." → retrieve_payment then refund_payment
• "How many ACTIVE subscriptions do we have, and show me the ones for customer CUST-42." → search_subscriptions

Example tool call

Arguments passed to check_bin:

{
  "binNumber": "554960",
  "locale": "en"
}

Returns iyzico's response as pretty-printed JSON, e.g.:

{
  "status": "success",
  "binNumber": "554960",
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Bonus",
  "bankName": "Garanti Bankası",
  "bankCode": 62,
  "commercial": 0
}

---

How authentication works

Every request is signed with iyzico's IYZWSv2 scheme:

1. Generate a random per-request key (sent in the x-iyzi-rnd header).
2. Compute HMAC-SHA256(randomKey + uriPath + JSON(body), secretKey) as lowercase hex. For GET endpoints the body is {} and parameters travel in the query string.
3. Build apiKey:<key>&randomKey:<rnd>&signature:<hex>, base64-encode it, and send it as Authorization: IYZWSv2 <base64>.

This is implemented in src/auth.ts and covered by test/auth.test.mjs.

---

Development

npm install       # install dependencies
npm run build     # compile TypeScript to dist/
npm test          # build, run the auth unit test, and the stdio smoke test
npm run list-tools # print the tool catalog as JSON

The smoke test launches the built server over stdio without any API key and verifies the MCP handshake, the full tool catalog, tool annotations, and that a credential-less call returns a clean, actionable error — so it runs safely in CI with no secrets.

Project layout

src/
  index.ts            CLI entrypoint (stdio transport, --list-tools/--help)
  server.ts           Builds the McpServer and registers all tools
  client.ts           HTTP client: signing, query strings, timeouts, error mapping
  auth.ts             IYZWSv2 HMAC-SHA256 request signing
  config.ts           Env-var configuration + validation
  tools/
    shared.ts         Common request fields, result/error helpers, tool type
    index.ts          Tool registry
    ping.ts, checkBin.ts, installmentInfo.ts, checkoutForm.ts,
    retrievePayment.ts, cancelPayment.ts, refundPayment.ts, subscriptions.ts
test/
  auth.test.mjs       Signature/authorization-header unit test
  smoke.mjs           End-to-end stdio handshake + tool-catalog test

---

Safety notes

• The server defaults to sandbox. Set IYZICO_ENVIRONMENT=production only when you intend to move real money.
• cancel_payment and refund_payment are irreversible. They are flagged destructive for MCP clients, but you remain responsible for confirming intent.
• Never pass full card numbers to check_bin — only the 6-8 digit BIN.
• Keep your secret key out of source control. Use environment variables or your MCP client's secret storage.

---

License

MIT © Seyithan Alkan