@vonpay/checkout-mcp

Model Context Protocol server for Von Payments Checkout. Lets AI agents (Claude Desktop, Cursor, Claude Code, any MCP-compatible client) drive the full Von Payments lifecycle on your behalf — hosted checkout sessions, discrete payment intents (auth / capture / void), refunds, network-token storage, and structured error diagnosis.

v0.4.x — 11 tools across the full lifecycle. Adds create_payment_intent, capture_payment_intent, void_payment_intent, create_refund, and create_token (since 0.4.0) plus folded dev-surface QA fixes through 0.4.1.

Install

npm install -g @vonpay/checkout-mcp

Requires: Node 20+.

Configure

Set your Von Payments API key in the MCP client config. Use a test-mode key (vp_sk_test_...) — the MCP server refuses to start without one.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "vonpay": {
      "command": "npx",
      "args": ["-y", "@vonpay/checkout-mcp"],
      "env": {
        "VON_PAY_SECRET_KEY": "vp_sk_test_..."
      }
    }
  }
}

Claude Code

Add to ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "vonpay": {
      "command": "npx",
      "args": ["-y", "@vonpay/checkout-mcp"],
      "env": { "VON_PAY_SECRET_KEY": "vp_sk_test_..." }
    }
  }
}

Cursor

Settings → MCP → Add Server → npx -y @vonpay/checkout-mcp, with VON_PAY_SECRET_KEY env.

Tools exposed

Hosted checkout

| Tool | Purpose | |---|---| | vonpay_checkout_create_session | Create a hosted-checkout session; returns id and checkoutUrl (buyer redirects there) | | vonpay_checkout_get_session | Fetch session status by ID | | vonpay_checkout_simulate_payment | Describe what a succeeded / failed / expired outcome looks like (synthetic — does not submit a real payment) |

Payment-intent lifecycle

For flows that don't use the hosted redirect — recurring billing, MIT, saved-card charges, fulfillment-on-ship auth/capture splits, post-settlement refunds.

| Tool | Purpose | |---|---| | vonpay_checkout_create_payment_intent | Create an intent (auth-only or auth+capture). Pass mit for merchant-initiated. Returns status: requires_action \| authorized \| succeeded | | vonpay_checkout_capture_payment_intent | Capture an authorized intent (full or partial amount); typically called at fulfillment | | vonpay_checkout_void_payment_intent | Release an auth hold before capture (cancellation pre-fulfillment) | | vonpay_checkout_create_refund | Refund a captured intent (full or partial); refund IDs use vpr_* prefix | | vonpay_checkout_create_token | Tokenize a payment method. All tokens use the vp_pmt_* prefix; reusability is governed by the setupForFutureUse field (omit/null → single-use; "on_session" → in-session reuse like upsells; "off_session" → recurring/MIT). Stripe-aligned semantics — no separate "reusable" token type |

Diagnostics

| Tool | Purpose | |---|---| | vonpay_checkout_health | Check API health and latency | | vonpay_checkout_list_test_cards | List sandbox test card numbers and their outcomes | | vonpay_checkout_diagnose_error | Take an error code, return { retryable, nextAction, llmHint, fix, docs, agentInstructions }. Pure-data; no API call. |

All tools validate input with Zod before calling the API. Errors surface as structured VonPayError JSON (code, fix, docs URL, request ID).

Safety

• Test-mode strongly recommended. The server accepts any key the API accepts; live keys hit live money. Use vp_sk_test_* for agent development.
• Destructive operations are now exposed. void_payment_intent releases an auth hold; create_refund returns funds. Both are gated by API key scope — use test-mode for agent experimentation. The diagnose_error tool's agentInstructions always says "do not retry" for terminal states (declined / voided), preventing accidental loops.
• Idempotency-aware. Every create-style tool accepts an idempotencyKey parameter so an agent retrying after a network hiccup gets the same result back rather than double-charging.
• No secret leakage. API key is read from VON_PAY_SECRET_KEY and never echoed to tool responses.
• No PAN handling. Card data never passes through this MCP server. Tokenization happens in vora-js iframes (browser-side) or via SDK-provided providerReference (server-side).

Documentation

• MCP server reference
• AI agent integration guide
• API reference

License

MIT