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

| Tool | Description | |---|---| | create_payment_intent | Create a payment intent | | get_payment_intent | Get a payment intent by ID | | create_source | Create a GCash/GrabPay source | | get_source | Get a source by ID | | create_payment | Charge a source to create a payment | | list_payments | List payments (cursor pagination) |

Refunds

| Tool | Description | |---|---| | create_refund | Refund a payment | | get_refund | Get a refund by ID | | list_refunds | List refunds (cursor pagination) |

Checkout & Links

| Tool | Description | |---|---| | create_checkout | Create a hosted checkout session | | get_checkout | Get a checkout session by ID | | create_link | Create a no-code Payment Link | | get_link | Get a link by ID or reference number | | archive_link | Archive / unarchive a link |

Webhooks

| Tool | Description | |---|---| | create_webhook | Register a webhook endpoint | | list_webhooks | List webhooks | | get_webhook | Get a webhook by ID | | update_webhook | Update URL/events, enable/disable | | verify_webhook_signature | Verify the Paymongo-Signature header locally (no API call) |

Payment Methods & Customers

| Tool | Description | |---|---| | create_payment_method | Create a payment method (e.g. a card) | | get_payment_method | Get a payment method by ID | | create_customer | Create a customer | | get_customer | Get a customer by ID | | list_customers | List customers (cursor pagination) |

Quick Start

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

Environment Variables

| Variable | Required | Description | |---|---|---| | PAYMONGO_SECRET_KEY | Yes | Secret API key from the PayMongo dashboard (sk_test_… or sk_live_…). | | PAYMONGO_ALLOW_LIVE | No | Must be "true" to allow money-moving tools when a live key is used (see Safety). |

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