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

12 tools across the full lifecycle (3.0.1). On a live key, money actions run only after a person approves them in your MCP host's own confirmation prompt. Tool results are allowlisted — credentials, merchant metadata and buyer identity never enter the agent's context.

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_get_payment_intent | Look up a payment intent's stored state (read-only; only succeeded means captured) | | 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 (paymentIntent) or a settled transaction (transaction) — exactly one — full or partial; refund IDs use vpr_* prefix. Only refund an id (payment intent or transaction) from your own order records: both are visible to the shopper's browser | | 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.
• Live keys need a person's approval for each money action (3.0.0+). On a vp_sk_live_* key, create_payment_intent, capture_payment_intent, void_payment_intent, create_refund and reusable-card create_token ask the person to approve the specific action, amount and id through your MCP host's own confirmation prompt (MCP elicitation), and run only if they accept. Your host must support elicitation — if it does not, those tools are refused on a live key. confirmLive: true is still required but is set by the AI model, so it is not the safeguard. The prompt is drawn by your host, so this protection is only as trustworthy as that host: do not use a host that approves prompts automatically. Sandbox keys (vp_sk_test_*) are unaffected.
• 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