MCP Server

The @vonpay/checkout-mcp package lets AI assistants interact with the Von Payments API using the Model Context Protocol (MCP).

MCP is an open standard that gives AI assistants the ability to call external tools. Instead of writing API calls by hand, an AI agent can create checkout sessions, check payment status, and preview test payment outcomes through natural language.

Setup

Claude Desktop

Add the following to your Claude Desktop MCP config (claude_desktop_config.json):

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

Cursor

Add the same configuration to your Cursor MCP settings (.cursor/mcp.json):

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

Available Tools

vonpay_checkout_create_session

Create a checkout session.

Parameter	Type	Required	Description
amount	integer	Yes	Amount in minor units (e.g. 1499 = $14.99)
currency	string	Yes	Three-letter ISO 4217 currency code
country	string	No	Two-letter ISO 3166-1 alpha-2 country code
description	string	No	Order description (max 500 characters)
successUrl	string	No	Redirect URL on success (http/https only)
cancelUrl	string	No	Redirect URL on cancel (http/https only)
metadata	object	No	Key-value metadata: up to 50 keys, keys up to 64 characters, values up to 500 characters

vonpay_checkout_get_session

Retrieve a session by ID.

Parameter	Type	Required	Description
sessionId	string	Yes	The session ID to look up (vp_cs_test_* or vp_cs_live_*)

vonpay_checkout_simulate_payment

Return a synthetic, shape-only preview of what a succeeded, failed, or expired outcome looks like. This tool does not call the API, does not look up the session, and does not change any session state — use it to preview the shape of a real webhook or session payload while building an integration. The sessionId you pass is echoed back in the synthetic response rather than looked up, and both test (vp_cs_test_*) and live (vp_cs_live_*) session IDs are accepted.

Parameter	Type	Required	Description
sessionId	string	Yes	The session ID to use in the synthetic response (not looked up)
outcome	string	Yes	One of: succeeded, failed, expired

vonpay_checkout_health

Check the API health status. No parameters.

vonpay_checkout_list_test_cards

List all available test card numbers. No parameters. See Test Cards for the full table.

vonpay_checkout_create_payment_intent

Create a payment intent for server-driven flows — recurring billing, MIT (merchant-initiated transactions), and saved-card charges — as a programmatic alternative to hosted checkout sessions (wraps POST /v1/payment_intents). Returns a PaymentIntent whose status discriminates the next action: requires_action (3DS — surface the nextAction URL to the buyer), authorized (call vonpay_checkout_capture_payment_intent next), captured (post-capture, pre-settle), or succeeded (terminal).

Moves money — requires human approval on live keys

⚠ MOVES MONEY — REQUIRES HUMAN APPROVAL ⚠ With the default captureMethod: "automatic" this charges the buyer immediately (→ succeeded), and an mit block charges a saved credential with no buyer present. An MCP host should require explicit human confirmation before invoking with a live key (vp_sk_live_*) — especially for automatic-capture or MIT charges — since an unconfirmed (e.g. prompt-injected) call moves real money. Sandbox keys (vp_sk_test_*) are safe to call without confirmation.

Parameter	Type	Required	Description
amount	integer	Yes	Amount in minor units (e.g. 1499 = $14.99)
currency	string	Yes	Three-letter ISO 4217 currency code
captureMethod	string	No	One of automatic (default — charges immediately on auth success) or manual (parks at authorized until you call capture)
metadata	object	No	Key-value metadata: up to 50 keys, keys up to 64 characters, values up to 500 characters
mit	object	No	Merchant-initiated transaction block for recurring / saved-card / retry charges. Omit for cardholder-initiated transactions. Capability gate: confirm supportedOperations.mit === true first
idempotencyKey	string	No	Idempotency key to make the charge safely retryable — same key returns the same intent rather than charging twice

vonpay_checkout_capture_payment_intent

Capture funds on an authorized payment intent (wraps POST /v1/payment_intents/{id}/capture). Call this after vonpay_checkout_create_payment_intent returned status: authorized (created with captureMethod: "manual") — typically at order fulfillment / ship time. The intent transitions to succeeded on success.

Moves money — requires human approval on live keys

⚠ DESTRUCTIVE — REQUIRES HUMAN APPROVAL ⚠ This call transfers funds from the buyer's account to the merchant. An MCP host should require explicit human confirmation before invoking. Live keys (vp_sk_live_*) move real money; sandbox (vp_sk_test_*) is safe to call without confirmation.

Parameter	Type	Required	Description
paymentIntentId	string	Yes	The payment intent to capture (vpi_test_* or vpi_live_*)
amountToCapture	integer	No	Partial-capture amount in minor units. Omit to capture the full authorized amount. Partial-capture support is binder-dependent — check supportedOperations.partialCapture first
idempotencyKey	string	No	Idempotency key for safe retries

vonpay_checkout_void_payment_intent

Void an authorized (uncaptured) payment intent (wraps POST /v1/payment_intents/{id}/void). Use this when the buyer changed their mind before fulfillment, or the order was cancelled while the intent was still in authorized state. Voiding releases the auth hold — no funds change hands.

Irreversible — requires human approval on live keys

⚠ DESTRUCTIVE — REQUIRES HUMAN APPROVAL ⚠ Voiding releases the auth hold irreversibly — the order cannot be captured afterwards. An MCP host should require explicit human confirmation before invoking; an automated void leaves a real order unfulfilled with no recovery path short of re-prompting the buyer for payment. Live keys (vp_sk_live_*) affect real money flows; sandbox (vp_sk_test_*) is safe to call without confirmation. You cannot void a captured intent on most binders — read supportedOperations.voidAfterCapture first; when its policy is rerouted_to_refund, prefer vonpay_checkout_create_refund instead.

Parameter	Type	Required	Description
paymentIntentId	string	Yes	The payment intent to void (vpi_test_* or vpi_live_*)
idempotencyKey	string	No	Idempotency key for safe retries

vonpay_checkout_create_refund

Refund a captured payment intent (wraps POST /v1/refunds). Use this when the payment intent is in succeeded state and you need to return funds to the buyer — order cancelled post-fulfillment, returned merchandise, billing dispute, etc. Refund IDs use the vpr_test_* / vpr_live_* prefix, and the returned Refund status is pending, succeeded, or failed; pending refunds settle asynchronously via the charge.refunded webhook.

Irreversible once settled — requires human approval on live keys

⚠ DESTRUCTIVE — REQUIRES HUMAN APPROVAL ⚠ This returns funds from the merchant to the buyer; once settled, a refund cannot be reversed by either party. An MCP host should require explicit human confirmation before invoking. Live keys (vp_sk_live_*) move real money; sandbox (vp_sk_test_*) is safe to call without confirmation.

Parameter	Type	Required	Description
paymentIntent	string	Yes	The payment intent to refund (vpi_test_* or vpi_live_*)
amount	integer	No	Refund amount in minor units. Omit to refund the full remaining balance (server computes authorized - previously refunded). Partial-refund support is binder-dependent — check supportedOperations.partialRefund
currency	string	No	Three-letter ISO 4217 currency code
reason	string	No	Free-form reason mirrored back on the refund record, for audit trails (max 500 characters)
metadata	object	No	Key-value metadata: up to 50 keys, keys up to 64 characters, values up to 500 characters
idempotencyKey	string	No	Idempotency key for safe retries

vonpay_checkout_create_token

Vault a card for later reuse (wraps POST /v1/tokens). Returns a vp_pmt_(test|live)_* payment-method token.

Requires human approval for reusable vaulting

With setupForFutureUse: "on_session" or "off_session" this mints a reusable credential that can be charged later with no buyer present. An MCP host should require explicit human confirmation before invoking it with either reusable scope on a live key — an unconfirmed (e.g. prompt-injected) call could vault a chargeable credential. Single-use vaulting (scope omitted) and sandbox keys (vp_sk_test_*) are low-risk.

Parameter	Type	Required	Description
setupForFutureUse	string	No	Reuse scope, captured at vault time: "on_session" (in-session reuse, e.g. upsells) or "off_session" (recurring / MIT, after explicit buyer consent). Omit for single-use — subsequent CIT/MIT charges then return payment_method_consent_missing (422).
providerReference	string	No	Iframe-minted vault handle from the browser-side card input (≤512 chars). Required on live keys for iframe-vault providers; optional in sandbox (a mock token is auto-minted if omitted).
buyerId	string	No	Buyer to attach the token to (≤128 chars). The server may also infer it from key context.
metadata	object	No	Key-value metadata: up to 50 keys, values up to 500 characters.
idempotencyKey	string	No	Idempotency key to make the vault call safely retryable.

Reusability is governed by the setupForFutureUse field on the vault row, not by a second prefix — the vp_pmt_* prefix is stable. Scope is set once at vault time; re-vault is required to upgrade it (e.g. null → "off_session") because the consent record must match what the buyer saw. See Tokenization for the full reusability model.

vonpay_checkout_diagnose_error

Diagnose a Von Payments error code and return structured self-heal guidance an agent can act on without a follow-up prompt. Pure data — no API call, no state change.

Parameter	Type	Required	Description
code	string	Yes	The error code to diagnose (lowercase identifier, e.g. auth_invalid_key, ≤64 chars). Unknown codes return a contact_support fallback.
status	integer	No	The HTTP status that came with the error (100–599), to help correlate.
requestId	string	No	The X-Request-Id from the error response (≤128 chars), for support escalation.

Returns a JSON object: { code, known, retryable, nextAction, llmHint, docs, agentInstructions[] } (plus status / requestId when you supplied them). nextAction is one of fix_input · rotate_key · wait_and_retry · contact_support · ignore (this is the MCP tool's own action vocabulary — distinct from the server error envelope's selfHeal.nextAction); agentInstructions is a short branch-specific playbook for that action. See Error Codes for the canonical per-code reference.

Example Agent Workflows

Create and preview a test payment

"Create a $14.99 checkout session in USD, then show me what a successful payment payload looks like."

The agent will:

1. Call vonpay_checkout_create_session with amount 1499, currency USD
2. Call vonpay_checkout_simulate_payment with outcome succeeded to preview the success payload shape (this is a synthetic preview — it does not change the real session)
3. Call vonpay_checkout_get_session to read the live session's current status

Preview error handling

"Create a session and show me what a failed payment payload looks like, including the error details."

The agent will:

1. Create a session
2. Call vonpay_checkout_simulate_payment with outcome failed to preview the failure payload shape (synthetic — no real payment is attempted)
3. Use the previewed shape to build the failure-handling path in the integration

Check system health

"Is the Von Payments API up?"

The agent calls vonpay_checkout_health and reports the status.