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

Tools

Prompts

accept_single_payment, refund_last_payment, debug_stuck_payment.

Resources

Install

One-click:

Or via npm:

npm install -g paypay-mcp

Configuration

Credentials come from the PayPay Developer Dashboard.

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