paymongo-mcp

MCP server for PayMongo — the Philippine payment gateway. Exposes payment intents, sources, payments, refunds, checkout sessions, payment links, webhooks, payment methods, and customers as MCP tools via Basic Auth.

Tools (24)

Payments

Refunds

Checkout & Links

Webhooks

Payment Methods & Customers

Related MCP server: vnpay-mcp

Quick Start

{
  "mcpServers": {
    "paymongo": {
      "command": "npx",
      "args": ["-y", "@theyahia/paymongo-mcp"],
      "env": {
        "PAYMONGO_SECRET_KEY": "<YOUR_PAYMONGO_SECRET_KEY>"
      }
    }
  }
}

Environment Variables

The server reads the secret key lazily — it can start and list its tools without a key set, so a missing key surfaces as a tool-call error rather than a startup crash.

Amounts

All amounts are integers in centavos (the smallest currency unit): 10000 = ₱100.00. PayMongo's minimum is typically 2000 (₱20.00) and varies by method.

Safety: test vs live keys

PayMongo keys are either test (sk_test_…) or live (sk_live_…). To prevent an AI agent from accidentally moving real money, the money-moving tools (create_payment, create_refund, create_payment_intent, create_source, create_checkout, create_link, create_payment_method) are refused when a live key is configured unless you opt in with:

PAYMONGO_ALLOW_LIVE=true

Read-only tools (get_*, list_*) always work. Tools are also tagged with MCP annotations (readOnlyHint / destructiveHint) so clients can auto-approve reads and warn on destructive actions.

Webhooks

Create a webhook to receive async payment events (e.g. source.chargeable, payment.paid):

create_webhook { "url": "https://your.app/paymongo/hook", "events": ["payment.paid", "source.chargeable"] }

The response includes a per-webhook signing secret (whsk_…). Store it. When PayMongo POSTs an event, verify the Paymongo-Signature header before trusting the body — pass the raw request body, the header value, and the signing secret to verify_webhook_signature:

verify_webhook_signature {
  "payload": "<raw request body, exactly as received>",
  "signature_header": "t=...,te=...,li=...",
  "webhook_signing_secret": "whsk_...",
  "mode": "test"
}

It computes HMAC-SHA256(timestamp + "." + body) and compares it (timing-safe) against the te (test) or li (live) segment. This tool runs entirely locally and needs no API key. Pass tolerance_seconds to also reject stale timestamps (replay protection).

Demo Prompts

• "Create a payment intent for 100 PHP"

• "Create a GCash source for 50 PHP with success/fail redirect URLs"

• "Create a payment link for 250 PHP for 'Consulting fee'"

• "List recent payments"

• "Refund 25 PHP from payment pay_123"

• "Register a webhook at https://example.com/hook for payment.paid"

Development

npm ci
npm run typecheck   # tsc --noEmit
npm run build       # tsc -> dist/
npm test            # vitest
npm run dev         # run from source with tsx

License

MIT