Skip to main content

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_..."
}
}
}
}

Environment​

VariableRequiredDescription
VON_PAY_SECRET_KEYYesA vp_sk_test_* or vp_sk_live_* key
VONPAY_BASE_URLNoAPI base URL. Defaults to https://checkout.vonpay.com
VONPAY_ALLOW_CUSTOM_BASE_URLNoExactly 1 lets a live key go to a base URL that is not a Von Payments API host, such as a proxy you run
VONPAY_MCP_TOOLSNoread registers only the tools that read (Read-only mode). all, the default, registers every tool. Any other value stops the server at startup
VONPAY_MCP_SHOW_TAG_VALUESNoExactly 1 shows your metadata tag values to the agent in a summary grouped by metadata. Hidden by default
VONPAY_MCP_SHOW_PRODUCT_NAMESNoExactly 1 shows your subscription product names and references to the agent. From 6.9.0 it also shows a subscription's brand name and store address, and a product's routing profile name, store links and public web page. Hidden by default
VONPAY_MCP_SHOW_MERCHANT_TEXTNoExactly 1 shows both of the above, except a kind whose own switch is set. A kind's own switch then decides: any value but exactly 1, such as 0, false or an empty value, keeps that kind hidden
VONPAY_MCP_LIVE_MAX_AMOUNTNoThe most one live money action may be for, per currency, in minor units: USD:50000 or USD:50000,EUR:40000. Other currencies are refused. It also covers a new subscription price, a fixed-amount discount and, from 6.9.0, a product price cut applied to existing subscribers
VONPAY_MCP_LIVE_MAX_ACTIONSNoThe most live money actions this server process attempts
VONPAY_MCP_MAX_CALLS_PER_MINUTENoThe most tool calls a minute, all tools together
VONPAY_AUDIT_LOGNooff turns off the local audit log
VONPAY_AUDIT_DIRNoWhere the audit log goes. Defaults to ~/.vonpay/audit
VONPAY_AUDIT_RETENTION_DAYSNoDays audit files are kept, 1 to 365. Default 30

With a live key, a VONPAY_BASE_URL other than https://checkout.vonpay.com or https://checkout-staging.vonpay.com stops the server at startup, before it answers any tool, unless VONPAY_ALLOW_CUSTOM_BASE_URL=1 is set. Sandbox keys are not restricted.

The three budget settings are off unless you set them. A call over budget is refused before anyone is asked. They are worth setting for a host that approves prompts automatically. A subscription price or discount is compared in the subscription's own currency, looked up first: a currency with no limit, or one that cannot be found, is refused, and so is a discount naming a different currency. A product price cut applied to existing subscribers is compared in the product's currency twice: the new price, and the cut. Either one over the limit is refused, and so is a cut that cannot be worked out.

Read-only mode​

With VONPAY_MCP_TOOLS=read (6.4.2 and later), the server registers only the tools that read: the payment list and summary, the three subscription product reads, the subscription payment tries (6.10.0), the get and look-up tools, and the local helpers. Nothing that charges, captures, voids, refunds, saves a card, creates a session or changes a subscription is registered. Use it for a reporting agent, with a restricted key that holds only payment_intents.read.

Read-only mode and the approval prompts are not a security boundary against an agent that can read the key or has a shell. The key's own permissions are.

Audit log​

From 6.4.2 the server writes one line per tool call to ~/.vonpay/audit/mcp-YYYY-MM-DD.jsonl (UTC date), so you can review after an incident what an agent did. It is on by default. A line holds the time, the tool, the key's mode and a short fingerprint of the key, the outcome, the API's error code and request id, and for money tools the amount, currency and target id. It never holds request bodies, metadata, notes, descriptions, URLs, emails, card data or idempotency keys. The log stays on your machine. If it cannot be written, the server prints one warning and the tool call carries on.

  • key_mode is test, live, publishable_test, publishable_live or unknown (a prefix the SDK does not know, gated as live). If you look for live lines, read unknown lines as live too. An unknown key's fingerprint is [unknown key] and a short hash.
  • Repeated refusals (from 6.5.0): the same refusal again and again is written once. A second copy of the line with "repeated": N then says N more came. A call that may have moved money is never collapsed.
  • A full day: a day's file holds at most 50 MiB (from 6.5.0, the last 5 MiB are kept for money lines, and a sandbox key's lines never use them). When even a money line no longer fits, the file ends with one line whose outcome is log_full, and nothing more is written that day.

Stopping the server​

From 6.5.0, stopping the server does not cut off a money call:

  • The host closes stdin: a tool call already running finishes, its reply and final audit line are written, and the server exits with code 0. An open approval prompt is refused, and nothing is sent.
  • SIGINT or SIGTERM: the server reads no more messages and refuses an open approval prompt. Running calls get up to 30 seconds and the audit log up to 2 seconds, then the server exits 130 or 143. A second signal stops the wait. A call still running at that point is named in one warning, and its pending audit line has no final line after it, so check that payment.

Available Tools​

Five of these tools move money: on a live key a person approves each call in your MCP host

create_payment_intent, capture_payment_intent, void_payment_intent, create_refund and create_token (with a reusable scope) act on real money or mint a chargeable credential. With a live key (vp_sk_live_*, or any key whose prefix the SDK does not know) each call needs confirmLive: true and the person's approval in the MCP host's own confirmation prompt. Sandbox keys (vp_sk_test_*) are never gated.

From version 3.0.0, a gated call on a live key passes these checks, in this order, before anything is sent:

  1. The host must support MCP elicitation, the protocol's way for a server to ask the person a question. A host that does not cannot run these five tools on a live key: each call is refused, with a message saying why. Stay on 2.x if you need the older behaviour on such a host.
  2. On the four payment tools, idempotencyKey must be on the call (from 4.0.0). create_payment_intent, capture_payment_intent, void_payment_intent and create_refund refuse a live-key call without one before confirmLive is checked or the person is asked. Approval is never remembered, so without a key an agent that asks twice would get two separately approvable payments. Use one key per intended action and send the same key on every retry whose outcome is unknown. After a definite answer (a refusal, or a refund that came back failed) the key is spent: a new attempt uses a new key.
  3. confirmLive: true must be on the call. Without it the tool returns an error result (isError: true) telling the agent to get its operator's approval, not to set the flag itself. Only true counts, never "yes" or 1.
  4. The person approves in the host's own prompt. It shows the action, the amount and currency when the call names them, and the payment intent, transaction or card id. Nothing else from the call appears in it, so notes, reasons and metadata never reach the prompt. Money moves only if the person ticks approve and accepts. Declining, dismissing, an error, or no answer within 5 minutes refuses the call and nothing is sent.

The AI model sets confirmLive, so the host prompt is the real safeguard. Your MCP host draws that prompt, not Von Payments, so it is only as trustworthy as the host: one that approves prompts automatically, or shows them to nobody, defeats it.

Approval is per call and never carries over from an earlier call in the conversation. confirmLive is on every gated tool's schema at all times, including with a sandbox key, so an agent that learned a tool against a test key sees it when pointed at a live one.

Each of the five is marked below with what is specific to it; create_token is gated only when setupForFutureUse is set, since single-use vaulting mints nothing that can be charged again.

From 6.4.2, create_session is approved by a person too on a live key: checks 1 and 4 apply. It takes no confirmLive and no idempotencyKey.

vonpay_checkout_create_session​

Create a checkout session.

ParameterTypeRequiredDescription
amountintegerYesAmount in minor units (e.g. 1499 = $14.99)
currencystringYesThree-letter ISO 4217 currency code
countrystringNoTwo-letter ISO 3166-1 alpha-2 country code
descriptionstringNoOrder description (max 500 characters)
successUrlstringNoRedirect URL on success. https, or another scheme only to localhost on a sandbox key
cancelUrlstringNoRedirect URL on cancel. Same rule as successUrl
metadataobjectNoKey-value metadata: up to 50 keys, keys up to 64 characters, values up to 500 characters

On a live key (6.4.2 and later), a person approves each session in the host's prompt. The prompt shows the amount, the currency, the hosts the buyer is sent to afterwards, and the description shoppers will read. A host that cannot ask is refused. On a live key any localhost or loopback address is refused, as the API refuses it.

vonpay_checkout_get_session​

Retrieve a session by ID.

ParameterTypeRequiredDescription
sessionIdstringYesThe session ID to look up (vp_cs_test_* or vp_cs_live_*)

The result includes vp_tx_id (the id create_refund takes as transaction) and vp_tx_count. When vp_tx_count is 2 or more the buyer was charged more than once and vp_tx_id is null: the tool tells the agent to stop and tell a person, not to refund.

From 6.9.0 the result also shows payment_method_card_check next to paymentMethod: whether an approved $0 card check stored the saved card (how the check works). { status: "approved", stored_credential_use } means a check stored it, and null means it was saved without one, or was checked before 13 November 2026 with no record of what the check declared. When the key is left out, it was not read. The tool tells the agent that neither answer is permission to charge the card.

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.

ParameterTypeRequiredDescription
sessionIdstringYesThe session ID to use in the synthetic response (not looked up)
outcomestringYesOne of: succeeded, failed, expired

vonpay_checkout_health​

Check the API health status. No parameters.

vonpay_checkout_list_test_cards​

Explains how to produce each test-mode outcome. No parameters, and no API call. It returns the order total that declines in test mode (with the decline_code and action it produces) and what a test payment needs. Same table as Test mode.

vonpay_checkout_get_payment_intent​

Read a payment intent's stored state: status, amount, capture method, timestamps, the saved-card token, the 3-D Secure result, nextAction while the buyer is still at their bank, and on a failed payment the decline reason (declineCode, action, declineMessage, ruleCode; from 5.5.0). When declineCode is blocked_by_rule, one of your own rules refused the payment: the assistant must not pass declineCode, declineMessage or ruleCode on to the buyer, only that the payment was declined. action is safe to use for retry guidance. Moves no money, so it is never gated. Only succeeded means the money was captured: authorized is a hold. Your metadata and the buyer's email are left out of the result, so they never enter the agent's conversation.

From 6.7.0 it also returns lateMoneyOutcome, for money that arrived after the payment read failed, cancelled or voided: reversed (given back), reversing (being given back) or reverse_failed (not given back yet; Von Payments finishes it). From 6.10.0 the agent is also told the values for money given back by hand: manual_refund_pending (not given back yet; Von Payments contacts you, and you may refund it by its settlement row), manually_refunded and kept_by_merchant, and that null means no late money arrived. It is told never to tell you to refund reverse_failed yourself, and that only an older server leaves the field out.

The tool never returns the card processor's own answer to a decline, the record of each try, or the card's first six digits. The processor's answer is untrusted text, so it must not reach the agent as if it were instructions. On the capture and void answers the agent sees the card's brand and last 4 only.

ParameterTypeRequiredDescription
paymentIntentIdstringYesThe payment intent to read (vpi_test_* or vpi_live_*)

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

Charges immediately unless you ask for manual capture

With the default captureMethod: "automatic" this charges the buyer straight away (→ succeeded), and an mit block charges a saved credential with no buyer present. On a live key: needs confirmLive: true and the person's approval; see above.

ParameterTypeRequiredDescription
amountintegerYesAmount in minor units (e.g. 1499 = $14.99)
currencystringYesThree-letter ISO 4217 currency code
captureMethodstringNoOne of automatic (default; charges immediately on auth success) or manual (parks at authorized until you call capture)
metadataobjectNoKey-value metadata: up to 50 keys, keys up to 64 characters, values up to 500 characters
mitobjectNoMerchant-initiated transaction block for recurring / saved-card / retry charges. Omit for cardholder-initiated transactions. Capability gate: confirm supportedOperations.mit === true first
paymentMethodobjectSaved card{ id }: the saved card to charge, a vp_pmt_test_… or vp_pmt_live_… token. A saved-card or recurring charge needs it; mit alone names no card
buyerIdstringSaved card (recommended)Your customer reference, up to 200 characters, from your own records. Send it on every saved-card charge: when the card was saved for a customer, a different buyerId is refused, so the card cannot be charged to the wrong customer
sessionIdstringNoThe checkout session this payment came from (vp_cs_test_… or vp_cs_live_…). When that session already charged the buyer, this charge is refused instead of charging twice. Safe to send every time
buyerEmailstringNoThe buyer's email, up to 254 characters, for a payment that does not start from a session
idempotencyKeystringLive keySame key returns the same intent rather than charging twice. Required on a live key. On a sandbox key, omitting it sends a generated key that protects only that one call
confirmLivebooleanLive keytrue only once a human approved this call; the host prompt follows. See above

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.

Transfers the funds

This moves money from the buyer's account to the merchant. On a live key: needs confirmLive: true and the person's approval; see above.

ParameterTypeRequiredDescription
paymentIntentIdstringYesThe payment intent to capture (vpi_test_* or vpi_live_*)
amountToCaptureintegerNoPartial-capture amount in minor units. Omit to capture the full authorized amount. Partial-capture support is binder-dependent: check supportedOperations.partialCapture first
idempotencyKeystringLive keyIdempotency key for safe retries. Required on a live key
confirmLivebooleanLive keytrue only once a human approved this call; the host prompt follows. See above

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.

Releasing the hold cannot be undone

A void releases the authorization irreversibly: the order cannot be captured afterwards, and there is no recovery short of asking the buyer to pay again. On a live key: needs confirmLive: true and the person's approval; see above. You cannot void a captured intent: supportedOperations.voidAfterCapture reads not_supported on every processor today, so once the intent is succeeded use vonpay_checkout_create_refund instead.

ParameterTypeRequiredDescription
paymentIntentIdstringYesThe payment intent to void (vpi_test_* or vpi_live_*)
idempotencyKeystringLive keyIdempotency key for safe retries. Required on a live key
confirmLivebooleanLive keytrue only once a human approved this call; the host prompt follows. See above

vonpay_checkout_create_refund​

Refund a captured payment intent, or a settled transaction (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. The returned Refund status is requested, succeeded, failed, or canceled; a refund the processor has accepted but not yet completed comes back as requested, which is in progress, not a failure. Do not re-issue it; it settles asynchronously via the charge.refunded webhook, or reports refund.failed if it does not complete. A charge.refunded can arrive while the refund is still pending on one card connection, so confirm the refund's status with GET /v1/refunds before you treat the money as returned. See Refunds.

A settled refund cannot be reversed

This returns funds from the merchant to the buyer, and once it settles neither party can undo it. On a live key: needs confirmLive: true and the person's approval; see above.

ParameterTypeRequiredDescription
paymentIntentstringOne of the twoThe payment intent to refund (vpi_test_* or vpi_live_*)
transactionstringOne of the twoThe transaction to refund (vp_tx_test_* or vp_tx_live_*): for a payment with no payment intent, or the transaction a refund_target_is_duplicate error names
amountintegerNoRefund amount in minor units. Omit to refund the full remaining balance (the server refunds what was captured, minus earlier refunds). Partial-refund support is binder-dependent: check supportedOperations.partialRefund
currencystringNoThree-letter ISO 4217 currency code
reasonstringNoFree-form reason mirrored back on the refund record, for audit trails (max 500 characters)
metadataobjectNoKey-value metadata: up to 50 keys, keys up to 64 characters, values up to 500 characters
idempotencyKeystringLive keyIdempotency key for safe retries. Required on a live key
sessionIdstringLive key, with transactionThe session this payment belongs to (vp_cs_*). Used only to check the transaction against the session before the person is asked; never sent with the refund. Refused with paymentIntent
confirmLivebooleanLive keytrue only once a human approved this call; the host prompt follows. See above

From 5.0.0, on a live key the approval prompt also shows details looked up from Von Payments, not supplied by the agent: the original payment's amount, status and creation time for paymentIntent, or the session's total, payment status, creation time and id for transaction. A refund larger than the looked-up amount, or in a different currency, adds a warning line. A refund by transaction is refused before the person is asked when its session cannot be found, when the session's vp_tx_count is not exactly 1, or when the transaction is not that session's payment. Sandbox keys skip these checks.

Pass exactly one of paymentIntent and transaction; both, or neither, is refused before anything is sent. The result names the target it refunded, with the other one null. Both ids are visible to the shopper's browser, so the tool tells the agent never to refund an id taken from a customer message or any text that did not come from your own order records.

vonpay_checkout_create_token​

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

A reusable scope mints a chargeable credential

With setupForFutureUse: "on_session" or "off_session" this vaults a credential that can be charged later with no buyer present, and with either scope, on a live key, the call needs confirmLive: true and the person's approval; see above. Single-use vaulting (the scope omitted) is low-risk and is not gated.

ParameterTypeRequiredDescription
setupForFutureUsestringNoReuse scope, captured at vault time: "on_session" (in-session reuse, e.g. upsells) or "off_session" (recurring / MIT, after explicit buyer consent). Omitted, a later merchant-initiated charge against the card returns payment_method_consent_missing (422).
providerReferencestringNoIframe-minted vault handle from the browser-side card input (≤512 chars). Optional in the tool's schema, but the API requires it with a test key and with a live key, and refuses the call without it (400 validation_error).
buyerIdstringNoBuyer to attach the token to (≤128 chars). The server may also infer it from key context.
metadataobjectNoKey-value metadata: up to 50 keys, values up to 500 characters.
idempotencyKeystringNoIdempotency key to make the vault call safely retryable.
confirmLivebooleanLive key + reusable scopetrue only once a human approved this call; the host prompt follows. See above

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.

Subscription tools​

From 6.3.0, for businesses with Subscriptions switched on. Each tool wraps one subscription call:

ToolDoes
vonpay_checkout_list_subscriptionsLists subscriptions (read only)
vonpay_checkout_get_subscriptionReads one subscription (read only)
vonpay_checkout_list_subscription_attemptsLists every payment try for a subscription, newest first (read only, 6.10.0 and later)
vonpay_checkout_cancel_subscriptionCancels now, or at the end of the paid period
vonpay_checkout_unschedule_subscription_cancelWithdraws a cancel scheduled for the end of the period
vonpay_checkout_pause_subscriptionPauses renewals
vonpay_checkout_resume_subscriptionResumes a paused subscription
vonpay_checkout_skip_subscription_renewalSkips the next renewal
vonpay_checkout_set_subscription_next_bill_dateMoves the next charge to a date
vonpay_checkout_set_subscription_intervalChanges how often it renews
vonpay_checkout_set_subscription_priceSets its renewal price
vonpay_checkout_set_subscription_discountSets a discount on future renewals
vonpay_checkout_remove_subscription_discountRemoves the discount
  • Every change needs an idempotencyKey, on every key, unless it is a dry run. Without one, the tool refuses the call before sending anything.
  • On a live key, every change needs confirmLive: true and the person's approval in the host's prompt, as for the payment tools above.
  • The agent sees only the subscription's operational fields. The customer's buyer_id and your metadata are left out.
  • Each change is recorded with the actor label vonpay-mcp, which comes back as actor.label on the subscription.updated event.
  • From 6.8.0, the agent sees heldReason on a subscription it reads or changes: why it is held (the reasons). A value that is not shaped like a code reads [unrecognised value withheld].
  • On a restricted key, the next bill date, interval, price and discount tools need subscriptions.write_billing; the tool descriptions say so from 6.8.0.
  • From 6.9.0, the agent sees customerPause: whether the customer may pause now, why not, and the latest resume date (customer pauses). The pause tool never sends customerRequested, so its pauses are your own and the setting does not limit them. A subscription_pause_too_long refusal shows maxCycles and maxResumesOn.
  • From 6.9.0, the agent sees brand and store. The brand name and the store address are hidden by default ([brand name hidden], [store address hidden]), like product names.

Subscription product tools​

Three tools read your subscription products (the list and the terms from 6.5.0, one product from 6.9.0). They move no money, are never gated, need no idempotency key, and stay in read-only mode.

ToolDoesRestricted key needs
vonpay_checkout_list_subscription_productsYour products in the key's mode, newest first, with prices, how often each renews, status and terms. Filters productRef and status, limit 1 to 100 (default 10), next page with startingAftersubscriptions.read, subscriptions.write or payment_intents.write
vonpay_checkout_get_subscription_productOne product by id or reference, with its routing profile, store links, how many subscriptions use it and its warningssubscriptions.read, subscriptions.write or subscription_products.write
vonpay_checkout_get_subscription_product_termsOne product's terms by id or reference: the sentence to show before the first charge, the price phrase and the terms version. Optional amount for an intro first paymentpayment_intents.write, so a strictly read-only key cannot run it

From 6.9.0, five tools change products, with the same rules as the API:

ToolDoes
vonpay_checkout_create_subscription_productCreates a product
vonpay_checkout_update_subscription_productChanges its name, routing profile, schedule, store links or public web page
vonpay_checkout_change_subscription_product_priceChanges its renewal price
vonpay_checkout_archive_subscription_productArchives it
vonpay_checkout_unarchive_subscription_productUnarchives it
  • A restricted key needs subscription_products.write. It also needs subscriptions.write_billing for a price cut applied to existing subscribers, and for an update that sets or removes the routing profile.
  • Every change needs an idempotencyKey, on every key. Without one, the tool refuses the call before sending anything. There is no dry run.
  • On a live key, every change needs confirmLive: true and the person's approval in the host's prompt. The server first looks the product up by its id. A product named by its reference, or one that cannot be looked up, is refused before the person is asked.
  • The price tool sends applyToExisting: false (new sign-ups only) when the agent leaves it out. With applyToExisting: true it lowers what existing subscribers pay, so the prompt says so and VONPAY_MCP_LIVE_MAX_AMOUNT applies.
  • Each change is recorded with the actor label vonpay-mcp.
  • Read-only mode drops all five.

The agent sees product #1, product #2 and so on in place of your product names and references, with the real ids, prices and terms. From 6.9.0 the routing profile's name, the store links' details and the product's public web page are hidden too. publicUrlAllowed, whether subscribers see that page now, is always shown. To show them, a person sets VONPAY_MCP_SHOW_PRODUCT_NAMES=1 or VONPAY_MCP_SHOW_MERCHANT_TEXT=1 in the MCP configuration (Environment). While names are hidden, a refusal's text is scrubbed of the names this server has seen, but a refusal naming a product it has not seen still shows that name. A long terms sentence reaches the agent cut, ending in … [cut], so show a customer the full text from the API.

Payment report tools​

From 6.4.2. Both read payment reports, move no money and are never gated. Use a restricted key with only payment_intents.read.

ToolDoes
vonpay_checkout_list_payment_intentsOne page of payment intents, newest first, with filters: a window of at most 31 days, status, outcome, store, one metadata tag (metadataKey and metadataValue), card brand, currency, initiator and decline code. For the next page, call again with exactly the same arguments plus startingAfter set to nextCursor. Never returns the buyer's identity or your metadata
vonpay_checkout_summarize_approvalsCounts, amounts and the approval, bank decline and decline rates, as your dashboard counts payment attempts, optionally grouped in a time zone. A rate with no traffic is null, never 0%. generatedAt says when the figures were computed (up to about 45 seconds old)

From 6.7.0, vonpay_checkout_list_payment_intents shows each payment's tries as a summary: attempts with only connectionId, result, declineCode and outcome, and attemptsStatus. The agent can count approvals and declines per connection, and counts them only when attemptsStatus is complete. It never sees the processor's own answer, the connection's name or the card's first six digits.

In a summary grouped by metadata, the agent sees tag value #1, tag value #2 and so on, with the real counts and rates. To show the real tag values, a person sets VONPAY_MCP_SHOW_TAG_VALUES=1 or VONPAY_MCP_SHOW_MERCHANT_TEXT=1 in the MCP configuration (Environment).

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.

ParameterTypeRequiredDescription
codestringYesThe error code to diagnose (lowercase identifier, e.g. auth_invalid_key, ≤64 chars). Unknown codes return a contact_support fallback.
statusintegerNoThe HTTP status that came with the error (100–599), to help correlate.
requestIdstringNoThe 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 · reconcile (reconcile: the outcome is unknown, so read the payment intent back and never retry; 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.

Upgrading to 6.10.0​

Needs @vonpay/checkout-node 4.13.0. Nothing to change.

New: vonpay_checkout_list_subscription_attempts, the late-money values for money given back by hand on get_payment_intent, derivedAmount and lineIndex in the error answer, and the corrected create_refund text: charge.refunded can arrive while the refund is still pending.

Upgrading to 6.9.0​

Needs @vonpay/checkout-node 4.11.0. Check:

  • A live spending limit now also covers a product price cut applied to existing subscribers (Environment).

New: the product read and the five product changes, payment_method_card_check on get_session, and customerPause, brand and store on the subscription tools' results.

Upgrading to 6.8.0​

Needs @vonpay/checkout-node 4.10.0. Check:

  • A reader of change warnings. A withheld warning code now reads [unrecognised value withheld] (it was [unrecognised code withheld]).

New: heldReason on the subscription tools' results. The next bill date, interval, price and discount tools say that a restricted key needs subscriptions.write_billing; the API already asks for it. For a restricted-key refusal, diagnose_error now asks for a new restricted key with the named permission first, and suggests a full secret key only as a last resort.

Upgrading to 6.7.0​

Nothing to change. New: lateMoneyOutcome on get_payment_intent, and the tries summary on the payment list.

Upgrading to 6.5.0​

Needs @vonpay/checkout-node 4.7.0. Check:

  • A live spending limit now also covers subscription changes. With VONPAY_MCP_LIVE_MAX_AMOUNT set, a new subscription price or fixed-amount discount above it is refused, as budget_refused in the audit log.
  • A reader of the audit log: key_mode can now be unknown, or a publishable type where it used to read live. Refusals can collapse into a repeated line, and a full file ends with log_full.
  • A key whose prefix is not known now gets the startup warning for a live key, and a key starting vp_pk_ that is neither publishable type is gated as live.

New: the subscription product tools, VONPAY_MCP_SHOW_MERCHANT_TEXT (Environment), and how the server stops.

Upgrading to 6.4.2​

Needs @vonpay/checkout-node 4.5.0. Install 6.4.2: 6.4.0 and 6.4.1 were never published. Check:

  • create_session asks a person on a live key, as the money tools do. A host that cannot ask is refused.
  • successUrl and cancelUrl follow the API's rule: https, or another scheme only to localhost. On a live key, any localhost or loopback address is refused.
  • The metadata key mirror is never sent by create_session, create_payment_intent, create_refund or create_token. The answer carries a note saying it was dropped.
  • Summary tag values are hidden unless you show them (Environment).
  • A new folder, ~/.vonpay/audit, appears on first use for the audit log.

New: the payment report tools, read-only mode, the optional live budget settings in Environment, and nextChangeAllowedOn on a 409 subscription_customer_change_limit_reached.

Upgrading to 6.3.0​

Needs @vonpay/checkout-node 4.4.0. New:

Upgrading to 6.2.0​

Needs @vonpay/checkout-node 4.3.0. Check:

  • Every key that is not a sandbox key is gated as live. The money tools ask for the person's approval in the host, confirmLive and an idempotencyKey for any key that is not vp_sk_test_…, not only for vp_sk_live_…. Such a key is also refused at startup for a base URL that is not a Von Payments API host, unless VONPAY_ALLOW_CUSTOM_BASE_URL=1.
  • A call with no arguments is read as empty arguments, as the MCP specification allows. A tool with required fields names each missing one.

New:

  • The payment-intent tools return networkAdvice, networkAdviceRetryAfterMs and mitAnchorSource (Decline handling). null advice is never permission to retry.
  • diagnose_error knows the three settle-only refusals and the two restricted-key refusals. The tool error carries their facts: the store order's balance and status, or the key's limit and refused fields.
  • create_refund reuses the same idempotencyKey only when the outcome is unknown. After a definite answer (a refusal, or a refund that came back failed) that key is spent, so a new attempt uses a new key after the person has checked the payment's refunds. This server has no tool that reads refunds: list them with GET /v1/refunds, the Node SDK's refunds.list() or the CLI's refunds list.
  • Tool arguments are validated with zod 4.6.7 (security advisory GHSA-mrhx-c7xc-m3w5), and the MCP toolkit moves to 1.32.

Upgrading to 6.0.0​

  • A live key pointed at another host no longer starts. If VONPAY_BASE_URL is set to anything but a Von Payments API host, unset it, or set VONPAY_ALLOW_CUSTOM_BASE_URL=1 for a proxy you run (Environment).
  • An unknown money outcome is not retryable. When a charge, capture, void or refund fails and its outcome is unknown, the tool's error now carries retryable: false and nextAction: "reconcile". Read the payment back first, and if you then retry, reuse the same idempotencyKey.

Everything else, including the live-key approval steps above, is unchanged.