paypay-mcp

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.1.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.

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:

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

... View full README on GitHub