Skip to main content
Glama

paypay-mcp

npm version npm downloads MCP Badge License: MIT

Model Context Protocol server for the PayPay Open Payment API.

Works with Claude Desktop, Claude Code, Cursor, Windsurf, Zed, ChatGPT Apps SDK, and any other MCP-compatible client. Tool descriptions are provided in English and Japanese.

Status

v0.2.x — production-capable, not yet battle-tested at scale.

The server runs cleanly against PayPay's production Open Payment API once PAYPAY_ENV=production is set with approved merchant credentials. It has not yet processed meaningful real-world volume. If you are routing real payments through it, pin the version and review the source first.

Related MCP server: paymongo-mcp

Tools

Tool

Description

create_qr_code

Create a dynamic PayPay QR code. Returns the payment URL, deeplink, and a rendered PNG.

get_payment_details

Fetch the current status of a payment.

wait_for_payment

Poll until a payment reaches a terminal state.

delete_qr_code

Invalidate a QR code before payment.

refund_payment

Full or partial refund. Disabled unless PAYPAY_ENABLE_REFUNDS=true.

cancel_payment

Cancel a payment when its state is unclear (timeout or error). Disabled unless PAYPAY_ENABLE_CANCELS=true.

Prompts

accept_single_payment, refund_last_payment, debug_stuck_payment.

Resources

URI

Description

paypay://docs/opa-reference

Endpoint map, auth scheme, and status vocabulary for the PayPay OPA API.

paypay://docs/payment-states

Payment lifecycle and the cancel-vs-refund decision rule.

paypay://config/current

Non-secret view of the active config (env, merchantId, baseUrl, transport).

Install

One-click:

Install in Cursor Install in VS Code

Or via npm:

npm install -g paypay-mcp

Configuration

Credentials come from the PayPay Developer Dashboard.

Variable

Required

Description

PAYPAY_API_KEY

yes

OPA API Key ID

PAYPAY_API_SECRET

yes

OPA API Key Secret

PAYPAY_MERCHANT_ID

yes

Merchant ID

PAYPAY_ENV

no

sandbox (default) or production

PAYPAY_ENABLE_REFUNDS

no

Set to true to expose refund_payment. Disabled by default.

PAYPAY_ENABLE_CANCELS

no

Set to true to expose cancel_payment. Disabled by default.

MCP_TRANSPORT

no

stdio (default) or http

MCP_HTTP_PORT

no

Port when MCP_TRANSPORT=http. Default 3000.

MCP_HTTP_HOST

no

Bind address. Default 127.0.0.1. Public binds require MCP_AUTH_TOKEN.

MCP_AUTH_TOKEN

no

Bearer token required on inbound HTTP requests when set. Mandatory for non-loopback binds.

MCP_HTTP_ALLOWED_ORIGINS

no

Comma-separated CORS allowlist. Default: none.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "paypay": {
      "command": "npx",
      "args": ["-y", "paypay-mcp"],
      "env": {
        "PAYPAY_API_KEY": "a_...",
        "PAYPAY_API_SECRET": "...",
        "PAYPAY_MERCHANT_ID": "...",
        "PAYPAY_ENV": "sandbox"
      }
    }
  }
}

Claude Code

claude mcp add paypay -e PAYPAY_API_KEY=... -e PAYPAY_API_SECRET=... -e PAYPAY_MERCHANT_ID=... -- npx -y paypay-mcp

Cursor

Add to ~/.cursor/mcp.json with the same shape as Claude Desktop.

Remote hosting

Run in HTTP mode. Public binds require MCP_AUTH_TOKEN; the server refuses to start otherwise.

MCP_TRANSPORT=http \
  MCP_HTTP_HOST=0.0.0.0 \
  MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  MCP_HTTP_ALLOWED_ORIGINS="https://claude.ai,https://your-app.example.com" \
  PAYPAY_ENV=sandbox \
  PAYPAY_API_KEY=... PAYPAY_API_SECRET=... PAYPAY_MERCHANT_ID=... \
  npx paypay-mcp

Endpoint: POST http(s)://<host>:3000/mcp (Streamable HTTP transport). Clients send Authorization: Bearer <MCP_AUTH_TOKEN>. CORS is closed by default.

For local testing the auth token can be omitted; the server binds to 127.0.0.1 and only accepts loopback connections.

Environments

Sandbox is the default. Production requires PayPay merchant onboarding (business verification and a contract) and must be enabled by explicitly setting PAYPAY_ENV=production.

Constraints

  • Amounts are integer JPY.

  • A payment can be canceled until 00:14:59 JST the day after the payment attempt. After that, use a refund.

  • A single order can receive multiple partial refunds, each with a unique merchantRefundId, up to the merchant-configured cap.

  • TLS 1.2+ required (Node 20+).

Development

git clone https://github.com/mrslbt/paypay-mcp.git
cd paypay-mcp
npm install
cp .env.example .env
npm run dev
npm test
npm run smoke
npm run build

Roadmap

v0.2: PreAuth + Capture, ContinuousPayments, DirectDebit, AccountLink QR, webhook signature verification, reconciliation tools.

v0.3: Native Payment (App Invoke + user JWT auth), Visa-partnership endpoints, OpenTelemetry tracing.

Safety

This server can move real money through the PayPay OPA API. Key safeguards:

  • Refund and cancel tools are disabled by default. refund_payment and cancel_payment are only registered when PAYPAY_ENABLE_REFUNDS=true or PAYPAY_ENABLE_CANCELS=true. Only enable them in trusted agent contexts where tool inputs cannot be influenced by untrusted content.

  • Sandbox is the default. Production requires an explicit PAYPAY_ENV=production, plus completed PayPay merchant onboarding. Always test against sandbox first.

  • Unique merchantPaymentId and merchantRefundId per call. PayPay deduplicates by these IDs, so reusing one will either fail or target an older payment. Generate a fresh ID for each new payment or refund.

  • Tools carry MCP safety annotations. Read-only tools (get_payment_details, wait_for_payment) are flagged readOnlyHint; money-moving and destructive tools (refund_payment, cancel_payment, delete_qr_code) are flagged destructiveHint so compatible clients can warn you before the call. These are advisory hints — the real guard is the gating above.

Even with these gates on, review any money-moving request before approving the tool call. Treat tool inputs derived from model output as untrusted.

Disclaimer

This is an unofficial, community-built MCP server. Not affiliated with, endorsed by, or sponsored by PayPay Corporation. PayPay is a registered trademark of its respective owners. Use at your own risk. The author accepts no liability for funds lost through misuse, prompt injection, or bugs.

License

MIT

Available Tools

4 tools
create_qr_codeCreate PayPay QR CodeA

Create a dynamic PayPay QR code that a customer can scan to pay. Returns the QR code both as a URL (deeplink + hosted image) and as an inline PNG image. Use wait_for_payment to poll until the customer completes the payment.

顧客がスキャンして支払うためのPayPay動的QRコードを作成します。 QRコードのURL(ディープリンクとホストされた画像)とインラインPNG画像の両方を返します。 顧客が支払いを完了するまで wait_for_payment でポーリングしてください。

Inputs: amount (required), order_description (required), code_type, order_items, +4 more.

delete_qr_codeDelete PayPay QR CodeA
DestructiveIdempotent

Invalidate a QR code before it is paid. Cannot be used after payment has completed. Use this when an order is canceled before checkout, or to clean up expired codes.

支払い前のQRコードを無効化します。決済完了後は使用できません。 注文がキャンセルされた場合や、期限切れのコードを整理する際に使用してください。

Inputs: code_id (required).

get_payment_detailsGet PayPay Payment DetailsA
Read-only

Fetch the current status and details of a payment by merchantPaymentId. Returns status: CREATED | AUTHORIZED | COMPLETED | REFUNDED | FAILED | CANCELED. Use this for one-off status checks. For active polling, prefer wait_for_payment.

merchantPaymentIdで指定した取引の現在のステータスと詳細を取得します。 ステータス: CREATED / AUTHORIZED / COMPLETED / REFUNDED / FAILED / CANCELED。 単発の確認に使用してください。継続的な確認は wait_for_payment を推奨します。

Inputs: merchant_payment_id (required).

wait_for_paymentWait for PayPay PaymentA
Read-only

Poll PayPay until a payment reaches a terminal state (COMPLETED, AUTHORIZED, REFUNDED, FAILED, CANCELED) or the timeout elapses. Uses PayPay's recommended 2–3s polling interval by default. Returns the final status and full payment detail.

取引が終了状態(COMPLETED / AUTHORIZED / REFUNDED / FAILED / CANCELED)に達するかタイムアウトするまで、PayPayをポーリングします。 PayPay推奨の2〜3秒間隔をデフォルトで使用します。 最終ステータスと取引詳細を返します。

Inputs: merchant_payment_id (required), timeout_seconds, poll_interval_seconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation4/5

    create_qr_code and delete_qr_code are clearly distinct lifecycle actions, and get_payment_details vs wait_for_payment are differentiated as one-off status checks vs polling. There is slight conceptual overlap between the two payment-status tools, but the descriptions make the intended use clear.

    Naming Consistency5/5

    All tool names follow a consistent verb-first snake_case pattern: create_qr_code, get_payment_details, delete_qr_code, wait_for_payment. The naming is predictable and easy to reason about.

    Tool Count5/5

    Four tools is appropriate for a narrowly scoped PayPay QR code payment server. The count feels focused rather than sparse, with no redundant or filler tools.

    Completeness4/5

    The core lifecycle is covered: create a QR code, poll/wait for payment, fetch payment details, and invalidate an unpaid QR code. A refund/cancel operation is absent even though REFUNDED appears in the status enum, but this is likely beyond the server's primary checkout-focused scope.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A comprehensive Model Context Protocol (MCP) server for BTCPayServer integration, providing tools for payment processing, store management, user administration, webhook handling and more with full API coverage.
      3
      68 npm
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for PayMongo payment gateway (Philippines). Supports payment intents, sources, payments, refunds, and checkout sessions via Basic Auth.
      24
      32 npm
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for Bank of Georgia iPay payment gateway, enabling payment orders, refunds, recurring payments, and pre-authorization via OAuth 2.0 + JWT.
      8
      16 npm
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP server for IDPay payment gateway (Iran). Supports payment creation, verification, inquiry, transaction listing, and payment links.
      8
      18 npm
      MIT