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
| Variable | Required | Description |
|---|---|---|
VON_PAY_SECRET_KEY | Yes | A vp_sk_test_* or vp_sk_live_* key |
VONPAY_BASE_URL | No | API base URL. Defaults to https://checkout.vonpay.com |
VONPAY_ALLOW_CUSTOM_BASE_URL | No | Exactly 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_TOOLS | No | read 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_VALUES | No | Exactly 1 shows your metadata tag values to the agent in a summary grouped by metadata. Hidden by default |
VONPAY_MCP_SHOW_PRODUCT_NAMES | No | Exactly 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_TEXT | No | Exactly 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_AMOUNT | No | The 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_ACTIONS | No | The most live money actions this server process attempts |
VONPAY_MCP_MAX_CALLS_PER_MINUTE | No | The most tool calls a minute, all tools together |
VONPAY_AUDIT_LOG | No | off turns off the local audit log |
VONPAY_AUDIT_DIR | No | Where the audit log goes. Defaults to ~/.vonpay/audit |
VONPAY_AUDIT_RETENTION_DAYS | No | Days 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_modeistest,live,publishable_test,publishable_liveorunknown(a prefix the SDK does not know, gated as live). If you look forlivelines, readunknownlines as live too. Anunknownkey'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": Nthen 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
outcomeislog_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
pendingaudit line has no final line after it, so check that payment.
Available Tools
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:
- 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.
- On the four payment tools,
idempotencyKeymust be on the call (from 4.0.0).create_payment_intent,capture_payment_intent,void_payment_intentandcreate_refundrefuse a live-key call without one beforeconfirmLiveis 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 backfailed) the key is spent: a new attempt uses a new key. confirmLive: truemust 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. Onlytruecounts, never"yes"or1.- 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.
| 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. https, or another scheme only to localhost on a sandbox key |
cancelUrl | string | No | Redirect URL on cancel. Same rule as successUrl |
metadata | object | No | Key-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.
| Parameter | Type | Required | Description |
|---|---|---|---|
sessionId | string | Yes | The 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.
| 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
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
paymentIntentId | string | Yes | The 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).
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.
| 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 |
paymentMethod | object | Saved 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 |
buyerId | string | Saved 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 |
sessionId | string | No | The 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 |
buyerEmail | string | No | The buyer's email, up to 254 characters, for a payment that does not start from a session |
idempotencyKey | string | Live key | Same 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 |
confirmLive | boolean | Live key | true 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.
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.
| 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 | Live key | Idempotency key for safe retries. Required on a live key |
confirmLive | boolean | Live key | true 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.
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
paymentIntentId | string | Yes | The payment intent to void (vpi_test_* or vpi_live_*) |
idempotencyKey | string | Live key | Idempotency key for safe retries. Required on a live key |
confirmLive | boolean | Live key | true 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.
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
paymentIntent | string | One of the two | The payment intent to refund (vpi_test_* or vpi_live_*) |
transaction | string | One of the two | The 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 |
amount | integer | No | Refund 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 |
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 | Live key | Idempotency key for safe retries. Required on a live key |
sessionId | string | Live key, with transaction | The 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 |
confirmLive | boolean | Live key | true 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.
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.
| 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). Omitted, a later merchant-initiated charge against the card returns payment_method_consent_missing (422). |
providerReference | string | No | Iframe-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). |
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. |
confirmLive | boolean | Live key + reusable scope | true 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:
| Tool | Does |
|---|---|
vonpay_checkout_list_subscriptions | Lists subscriptions (read only) |
vonpay_checkout_get_subscription | Reads one subscription (read only) |
vonpay_checkout_list_subscription_attempts | Lists every payment try for a subscription, newest first (read only, 6.10.0 and later) |
vonpay_checkout_cancel_subscription | Cancels now, or at the end of the paid period |
vonpay_checkout_unschedule_subscription_cancel | Withdraws a cancel scheduled for the end of the period |
vonpay_checkout_pause_subscription | Pauses renewals |
vonpay_checkout_resume_subscription | Resumes a paused subscription |
vonpay_checkout_skip_subscription_renewal | Skips the next renewal |
vonpay_checkout_set_subscription_next_bill_date | Moves the next charge to a date |
vonpay_checkout_set_subscription_interval | Changes how often it renews |
vonpay_checkout_set_subscription_price | Sets its renewal price |
vonpay_checkout_set_subscription_discount | Sets a discount on future renewals |
vonpay_checkout_remove_subscription_discount | Removes 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: trueand 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_idand yourmetadataare left out. - Each change is recorded with the actor label
vonpay-mcp, which comes back asactor.labelon thesubscription.updatedevent. - From 6.8.0, the agent sees
heldReasonon a subscription it reads or changes: why it isheld(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 sendscustomerRequested, so its pauses are your own and the setting does not limit them. Asubscription_pause_too_longrefusal showsmaxCyclesandmaxResumesOn. - From 6.9.0, the agent sees
brandandstore. 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.
| Tool | Does | Restricted key needs |
|---|---|---|
vonpay_checkout_list_subscription_products | Your 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 startingAfter | subscriptions.read, subscriptions.write or payment_intents.write |
vonpay_checkout_get_subscription_product | One product by id or reference, with its routing profile, store links, how many subscriptions use it and its warnings | subscriptions.read, subscriptions.write or subscription_products.write |
vonpay_checkout_get_subscription_product_terms | One 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 payment | payment_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:
| Tool | Does |
|---|---|
vonpay_checkout_create_subscription_product | Creates a product |
vonpay_checkout_update_subscription_product | Changes its name, routing profile, schedule, store links or public web page |
vonpay_checkout_change_subscription_product_price | Changes its renewal price |
vonpay_checkout_archive_subscription_product | Archives it |
vonpay_checkout_unarchive_subscription_product | Unarchives it |
- A restricted key needs
subscription_products.write. It also needssubscriptions.write_billingfor 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: trueand 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. WithapplyToExisting: trueit lowers what existing subscribers pay, so the prompt says so andVONPAY_MCP_LIVE_MAX_AMOUNTapplies. - 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.
| Tool | Does |
|---|---|
vonpay_checkout_list_payment_intents | One 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_approvals | Counts, 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.
| 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 · 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:
- Call
vonpay_checkout_create_sessionwith amount1499, currencyUSD - Call
vonpay_checkout_simulate_paymentwith outcomesucceededto preview the success payload shape (this is a synthetic preview; it does not change the real session) - Call
vonpay_checkout_get_sessionto 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:
- Create a session
- Call
vonpay_checkout_simulate_paymentwith outcomefailedto preview the failure payload shape (synthetic; no real payment is attempted) - 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_AMOUNTset, a new subscription price or fixed-amount discount above it is refused, asbudget_refusedin the audit log. - A reader of the audit log:
key_modecan now beunknown, or a publishable type where it used to readlive. Refusals can collapse into arepeatedline, and a full file ends withlog_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_sessionasks a person on a live key, as the money tools do. A host that cannot ask is refused.successUrlandcancelUrlfollow the API's rule:https, or another scheme only tolocalhost. On a live key, any localhost or loopback address is refused.- The metadata key
mirroris never sent bycreate_session,create_payment_intent,create_refundorcreate_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:
- When
create_payment_intentis refused before any money moved, the tool error carriespaymentIntentId: the failed payment intent that records the attempt (The record of a refused charge). Nothing was charged. Send the corrected charge with a newidempotencyKey. diagnose_errorknowspayment_intent_not_found,transaction_not_found,payment_method_not_storedandrecurring_mandate_required.- The webhook tools accept
merchant.card_testing_suspected. It is opt-in:"*"does not include it, so name it. - Subscription tools: list, read, cancel, withdraw a scheduled cancel, pause, resume, skip, next bill date, interval, price and discount.
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,
confirmLiveand anidempotencyKeyfor any key that is notvp_sk_test_…, not only forvp_sk_live_…. Such a key is also refused at startup for a base URL that is not a Von Payments API host, unlessVONPAY_ALLOW_CUSTOM_BASE_URL=1. - A call with no
argumentsis 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,networkAdviceRetryAfterMsandmitAnchorSource(Decline handling).nulladvice is never permission to retry. diagnose_errorknows 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_refundreuses the sameidempotencyKeyonly when the outcome is unknown. After a definite answer (a refusal, or a refund that came backfailed) 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 withGET /v1/refunds, the Node SDK'srefunds.list()or the CLI'srefunds 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_URLis set to anything but a Von Payments API host, unset it, or setVONPAY_ALLOW_CUSTOM_BASE_URL=1for 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: falseandnextAction: "reconcile". Read the payment back first, and if you then retry, reuse the sameidempotencyKey.
Everything else, including the live-key approval steps above, is unchanged.