Skip to main content

CLI

Command-line interface for Von Payments, powered by the @vonpay/checkout-cli package.

The vonpay command is the umbrella CLI. checkout is a product subcommand — all checkout-related commands live under vonpay checkout.

Install​

npm install -g @vonpay/checkout-cli

Authentication​

The CLI resolves your API key in this order:

  1. Environment variable VON_PAY_SECRET_KEY (takes precedence)
  2. Stored key saved by vonpay checkout login (persisted to ~/.vonpay/config.json)

The key must be a secret key: vp_sk_test_… (sandbox) or vp_sk_live_… (live). Any other key, including a publishable vp_pk_… key, is refused before anything is sent.

Live keys​

A live key moves real money, so the CLI treats it differently from a sandbox key:

  • A person confirms each money action at the terminal. payment-intents create, capture and void, refunds create, sessions create (from 0.18.0), trigger and listen show what they are about to do (the action, the amount, the idempotency key and the start of the key) and proceed only if you type confirm. Anything else cancels and nothing is sent.
  • Money commands need your own idempotency key (from 0.18.0). On a live key, payment-intents create, capture, void and refunds create refuse to run without --idempotency-key, before anything is sent. Choose one key per action, such as your order id plus the action (order_1042:refund), and pass the same key if you run the command again.
  • No terminal, no action. In a script, a CI job or an AI agent's shell, these commands refuse a live key and send nothing. Automate with a sandbox key.
  • Live keys are never saved to disk. login and init refuse a live key. Give it to the CLI for one session through VON_PAY_SECRET_KEY.
  • A live key goes only to a Von Payments API host (https://checkout.vonpay.com or https://checkout-staging.vonpay.com). To send it through a proxy you run, set VONPAY_ALLOW_CUSTOM_BASE_URL=1 and also pass --allow-custom-base-url on each command (0.18.0 and later). Either one alone is refused.

Sandbox keys are never asked to confirm.

Commands​

vonpay checkout login​

Interactively store your API key. The CLI prompts for your secret key and saves it to ~/.vonpay/config.json. Only sandbox keys are saved; a live key is refused (Live keys).

vonpay checkout login
# ? Enter your Von Payments secret key: vp_sk_test_...
# Key saved to ~/.vonpay/config.json

vonpay checkout logout​

Remove the stored API key from ~/.vonpay/config.json.

vonpay checkout logout
# ✓ Stored API key removed from ~/.vonpay/config.json

If VON_PAY_SECRET_KEY is still set in your environment, the CLI warns you: the env var takes precedence over the stored config, so you remain authenticated in that shell until you unset VON_PAY_SECRET_KEY.

vonpay checkout init​

Write a .env file in the current directory using the stored API key. A live key is never written; init works with sandbox keys only.

vonpay checkout init
# Created .env with VON_PAY_SECRET_KEY

vonpay checkout sessions create​

Create a checkout session from the command line.

vonpay checkout sessions create --amount 1499 --currency USD
FlagRequiredDescription
--amountYesAmount in minor units, a whole number (e.g. 1499 = $14.99)
--currencyYesThree-letter currency code
--countryNoTwo-letter country code (e.g. US)
--descriptionNoSession description
--success-urlNoRedirect URL on success
--cancel-urlNoRedirect URL on cancel
--idempotency-keyNoIdempotency key for safe retries
--dry-runNoValidate without creating a session
--jsonNoOutput raw JSON response, with the session's client secret masked
--show-secretsNoWith --json, print the client secret in full. The output then contains a secret, so do not paste it anywhere
# Dry-run validation
vonpay checkout sessions create --amount 1499 --currency USD --dry-run

# JSON output for scripting
vonpay checkout sessions create --amount 1499 --currency USD --country US --json

On a live key, a person confirms at the terminal before the session is created. The prompt shows the amount and the hosts the buyer is sent to after paying or cancelling. A dry run is not asked.

vonpay checkout sessions get​

Retrieve a session by ID.

vonpay checkout sessions get vp_cs_test_abc123
FlagDescription
--jsonOutput raw JSON response, with the session's client secret masked
--show-secretsWith --json, print the client secret in full. The output then contains a secret, so do not paste it anywhere

vonpay checkout payment-intents create​

Create a payment intent directly from the command line (the discrete auth/capture lifecycle, separate from sessions).

vonpay checkout payment-intents create --amount 1499 --currency USD
FlagRequiredDescription
--amountYesAmount in minor units, a whole number (e.g. 1499 = $14.99)
--currencyYesISO 4217 currency code (e.g. USD)
--capture-methodNoautomatic (default) or manual (parks at authorized)
--metadataNoMetadata key=value (repeat the flag for multiple pairs)
--mit-initiatorNoMIT initiator (merchant or customer)
--mit-reasonNoMIT reason (recurring, unscheduled, or installment)
--mit-original-transaction-idNoCardholder-initiated anchor payment intent ID (vpi_*)
--payment-methodNoStored card to charge (vp_pmt_*). Required for saved-card and recurring charges
--session-idNoCheckout session this charge belongs to (vp_cs_*). Refused if that session already charged
--buyer-idNoYour customer reference. Send it on every saved-card charge
--buyer-emailNoBuyer email for this charge
--idempotency-keyNo (sandbox), Yes (live)Key for this charge. Required on a live key. On a sandbox key, generated and printed when omitted
--jsonNoOutput raw JSON

The three --mit-* flags are all-or-nothing: supply all three to attach a merchant-initiated-transaction block, or none.

Every charge carries an idempotency key. On a sandbox key without --idempotency-key, the command generates one and prints it to stderr before sending, so --json output is unchanged. To retry the same charge, re-run with --idempotency-key <that value>. Re-running without it sends a new key, which is a new charge. On a live key the flag is required (Live keys).

Amounts are whole numbers in minor units: 14.99 or 1e3 is refused before anything is sent.

If a charge, capture, void or refund fails and its outcome is unknown, the error reads Next action: reconcile. Read the payment back first (payment-intents get, or refunds list for a refund) and act only on what it shows; if you then retry, reuse the same --idempotency-key, never a new one.

vonpay checkout payment-intents get​

Read a payment intent back. Use it first whenever an outcome is unclear.

vonpay checkout payment-intents get vpi_test_abc123
FlagDescription
--jsonOutput JSON, without the processor detail
--include-processor-detailWith --json, print the processor detail too (0.21.0 and later)

vonpay checkout payment-intents list​

List your payment intents, newest first, with filters (0.18.0 and later). It reads GET /v1/payment_intents. A read-only key with only payment_intents.read is enough, and a live key is not asked to confirm.

vonpay checkout payment-intents list --created-gte 2026-10-01T00:00:00-04:00 --outcome bank_declined
FlagDescription
--created-gte / --created-ltThe window: Unix seconds or an ISO 8601 time with a zone. At most 31 days
--status, --outcome, --card-brand, --decline-codeOnly these values, comma-separated
--storeOnly payments for this connected store hostname
--metadataOnly payments with this one metadata tag, key=value. From 0.21.0 a value over 128 characters is refused before anything is sent
--currencyOnly payments in this currency
--initiatormerchant (your charges on a saved card) or customer
--limitPage size, up to 100 (default 25)
--starting-afterThe cursor a previous run printed. Send exactly the same filters and window. It lasts 24 hours
--allRead every page, one request at a time
--max-itemsWith --all, stop after this many payments. The default is 10,000, and reaching it prints a note on stderr
--jsonOutput JSON. Each payment's status, outcome, amount, card, store and decline fields, and a summary of its tries, without your metadata
--include-metadataWith --json, print every field, your metadata included, but not the processor detail
--include-processor-detailWith --json, print the processor detail too (0.21.0 and later)

--json leaves your metadata out so that an AI agent reading the output does not read your own free text as instructions.

vonpay checkout payment-intents summary​

Counts, amounts and the approval, bank decline and decline rates for a window, as your dashboard counts payment attempts (0.18.0 and later). It reads GET /v1/payment_intents/summary.

vonpay checkout payment-intents summary --created-gte 2026-10-01T00:00:00-04:00 --group-by day,store --time-zone America/New_York

It takes the same filters as list, without --status, and:

FlagDescription
--group-byUp to 3 of hour, day, week, store, metadata, card_brand, currency, outcome and decline_code, with one time unit
--group-by-metadata-keyWith --group-by metadata: the metadata key whose values become groups
--time-zoneWhere hours, days and weeks start (default UTC)
--jsonOutput raw JSON

A rate with no traffic prints as "no data", never 0%. The output says when the figures were computed. A summary is kept for 45 seconds, so for fresh numbers change the window or wait.

vonpay checkout payment-intents capture​

Capture an authorized payment intent. Pass the payment intent ID (vpi_*) as the argument.

vonpay checkout payment-intents capture vpi_test_abc123
FlagDescription
--amount-to-capturePartial capture amount in minor units, a whole number (omit for a full capture)
--idempotency-keyIdempotency key. Required on a live key. On a sandbox key, generated and printed when omitted
--jsonOutput raw JSON

vonpay checkout payment-intents void​

Void an authorized (uncaptured) payment intent. Pass the payment intent ID (vpi_*) as the argument.

vonpay checkout payment-intents void vpi_test_abc123
FlagDescription
--idempotency-keyIdempotency key. Required on a live key. On a sandbox key, generated and printed when omitted
--jsonOutput raw JSON

vonpay checkout refunds create​

Create a refund against a captured payment intent, or against a transaction for a payment that has no payment intent.

vonpay checkout refunds create --payment-intent vpi_test_abc123
vonpay checkout refunds create --transaction vp_tx_test_abc123
FlagRequiredDescription
--payment-intentOne of the twoPayment intent ID to refund (vpi_*)
--transactionOne of the twoTransaction ID to refund (vp_tx_*): for a payment with no payment intent, or the transaction a refund_target_is_duplicate error names
--amountNoRefund amount in minor units, a whole number (omit for the full remaining balance)
--currencyNoISO 4217 currency code
--reasonNoFree-form reason (mirrored back on the record)
--metadataNoMetadata key=value (repeat the flag for multiple pairs)
--session-idWith --transaction on a live keyThe checkout session the payment belongs to (vp_cs_*). The transaction must be that session's single payment
--idempotency-keyNo (sandbox), Yes (live)Idempotency key. Required on a live key. On a sandbox key, generated and printed when omitted
--jsonNoOutput raw JSON

Pass exactly one of --payment-intent and --transaction; both, or neither, is refused before anything is sent. Both ids are visible to the shopper's browser, so refund only an id you looked up in your own order records.

On a live key, the CLI looks up the payment before you confirm and shows what was already refunded and what is still refundable. A refund by --transaction also needs --session-id (0.18.0 and later), and is refused unless the transaction is that session's single payment.

vonpay checkout refunds list​

List one payment's refunds, newest first, with the payment's refund totals. Use it to check a refund whose outcome was unclear before refunding again.

vonpay checkout refunds list --payment-intent vpi_test_abc123
FlagDescription
--payment-intentThe payment's payment intent ID (vpi_*). Use this or --transaction
--transactionThe payment's transaction ID (vp_tx_*)
--limitHow many refunds to show: a whole number of at least 1 (default 25). The API allows at most 100
--starting-afterThe next-page cursor printed by a previous run
--jsonOutput raw JSON

vonpay checkout subscription-products list​

List your subscription products in the key's mode, newest first (0.19.0 and later). Each shows its id, name, reference, status, first payment, renewal price, how often it renews and its terms sentence. A restricted key needs subscriptions.read, subscriptions.write or payment_intents.write.

vonpay checkout subscription-products list --status active
FlagDescription
--product-refOnly the product with this reference, matched exactly
--statusactive or archived
--limitPage size, 1 to 100 (default 10)
--starting-afterThe id the previous run printed, for the next page
--jsonOutput raw JSON

vonpay checkout subscription-products terms <product>​

Read one product's terms by id (vsprod_…) or reference (0.19.0 and later): the sentence to show next to the order button, the price phrase your own words must contain, the first payment, the renewal price and interval, and the terms version. A restricted key needs payment_intents.write.

vonpay checkout subscription-products terms vsprod_test_Hk29sLq0
FlagDescription
--amountRead the terms for an intro first payment, in minor units, at or below the product's price
--jsonOutput raw JSON

The text output prints at most 500 characters of the terms sentence or price phrase, and a longer one says it was cut. Read all of it with --json before you show it to a customer.

vonpay checkout subscription-products get <product>​

Read one product (0.22.0 and later): its price, schedule, routing profile, the stores it is sold in, and how many subscriptions use it. <product> is its id (vsprod_…), or the reference of an active product. Find an archived product by its id.

vonpay checkout subscription-products get vsprod_test_Hk29sLq0

Change subscription products​

From 0.22.0 the CLI makes the same product changes as the API. Each command prints the product as it is after the change, with any warnings (never a failure). A price cut that is still being applied prints how far it got instead. Changes take the product's id (vsprod_…), not its reference. A product is made in your account's mode: make test products on your sandbox account with its test key.

CommandWhat it does
createA new product. Needs --name, --product-ref, --renewal-price (minor units), --currency, --interval (day, week or month) and --interval-count (1 to 365). Optional: --routing-profile <vsrp_…>, --store-link.
update <product>A new --name, schedule (--interval with --interval-count), --routing-profile or --remove-routing-profile, --store-link or --remove-store-links. Send at least one. A schedule or routing change reaches new sign-ups only. Store links you give replace every current link, and the replaced links are dropped for good.
change-price <product>A new --renewal-price. A raise reaches new sign-ups only. A cut with --apply-to-existing also lowers subscriptions still on the old price, from their next charge. When the cut goes below a current keep-offer price, send new ones with --keep-offer-prices (minor units, separated by commas).
archive <product>No new sign-ups or customer switches to it. Existing subscribers keep renewing. Its reference is freed at once, so another product can take it.
unarchive <product>Opens the product to new sign-ups again. Refused when another active product now has its reference.
vonpay checkout subscription-products change-price vsprod_test_Hk29sLq0 \
--renewal-price 2499 --apply-to-existing --idempotency-key price-cut-2026-11
FlagDescription
--idempotency-keyRequired on every change, with every key, sandbox too. Use one key per change you mean to make, and the same key only to retry that exact change. The CLI never makes one up.
--actor-labelYour own name for the system making the change, for example campaign-tool, shown in the settings history: 1 to 64 lowercase letters, digits and _ . : -, starting with a letter or a digit. Never personal data.
--store-linkA store the product is sold in, as key=value pairs separated by commas: platform=nextcommerce,store=<store address>,store_product_id=<id>[,store_variant_id=<id>]. Repeat the flag for each store.
--jsonOutput raw JSON

A large price cut can take more than one run. The output then says it is still being applied: run the same command with the same --idempotency-key. The cut is saved, so the exit code is 0. A script must read outcome (completed or in_progress) in the --json output and run the command again on in_progress.

On a live key, a person confirms update, archive, unarchive and change-price --apply-to-existing at the terminal. Without a terminal (a script, a CI job or an AI agent) these are refused. create, and change-price without --apply-to-existing, are not confirmed: they change nothing for current subscribers.

vonpay checkout tokens create​

Create a payment-method token for saved-card / MIT flows.

vonpay checkout tokens create --buyer-id buyer_abc123
FlagDescription
--buyer-idBuyer ID to attach the token to
--provider-referenceProvider tokenization handle (required)
--metadataMetadata key=value (repeat the flag for multiple pairs)
--idempotency-keyIdempotency key for safe retries
--jsonOutput raw JSON

The server requires --provider-reference with a test key and with a live key: without it the request returns 400 validation_error.

vonpay checkout capabilities​

Show what this merchant account supports — auth/capture separation, partial capture, partial refund, void-after-capture policy, MIT, network tokens, 3-D Secure 2, ACH, payouts, settlement currencies, and rate limits.

vonpay checkout capabilities

# JSON output
vonpay checkout capabilities --json
FlagDescription
--jsonOutput raw JSON response

vonpay checkout trigger​

Send a signed test webhook event to a URL, including localhost, to verify your webhook handler during development. The CLI signs the payload with the same algorithm and header format as the live delivery engine: a single x-vonpay-signature header of the form t=<unix-seconds>,v1=<hex>, where v1 is an HMAC-SHA256 over ${t}.${body}.

Signing secret (0.18.0 and later). The CLI never signs with your API key. Each run makes a new random whsec_… secret and prints it at the start: verify the event with that value. To keep one secret across runs, for example in your handler's .env file, pin it with --signing-secret <secret> or VONPAY_CLI_SIGNING_SECRET (the flag wins). Pinning is the usual way for trigger, because the event is sent at once. A pinned secret needs at least 16 characters and no spaces, and a value that is or looks like an API key is refused. Production webhooks are signed with your endpoint's own whsec_* secret. See Webhooks: Test your handler for the full walkthrough.

vonpay checkout trigger charge.succeeded --url http://localhost:3000/webhooks/vonpay

Supported events include every charge.* event, payment_intent.succeeded, payment_intent.failed, payment_intent.cancelled, refund.failed, mirror.order.created, merchant.card_testing_suspected and the five subscription.* events (0.17.0 and later), session.succeeded and session.failed; a name the CLI does not know is rejected. payment_intent.authorized and payment_intent.held_for_review cannot be triggered. session.succeeded and session.failed are delivered to a subscription that selects them, but carry no saved card or vp_tx_id, so fulfill on charge.succeeded. See the full webhook event catalog for event payload shapes.

FlagRequiredDescription
--urlYesThe endpoint to deliver the test event to. Must be this machine (localhost, 127.0.0.1 or another loopback address) unless you pass --url-tunnel
--url-tunnelNoAllow a non-local --url, such as an ngrok or Cloudflare Tunnel address
--session-idNoUse a specific session ID instead of a generated one
--amountNoAmount in minor units, a whole number (defaults to 1499)
--currencyNoCurrency code (defaults to USD)
--signing-secretNoSign with this secret instead of a new random one (or set VONPAY_CLI_SIGNING_SECRET)

With a live key, a person confirms at the terminal first (Live keys).

vonpay checkout doctor​

Collect a diagnostic bundle: your environment, a live health probe, and — when a key is available — a round-trip against the API. Use it when something is failing and you cannot tell whether the problem is your setup, your key, or the service.

vonpay checkout doctor

# Machine-parseable, for your own tooling
vonpay checkout doctor --json

# Structured for an AI assistant to read and act on
vonpay checkout doctor --for-llm
FlagDescription
--jsonEmit the bundle as JSON instead of the readable table
--for-llmEmit structured markdown an assistant can act on without further prompting

It is safe to paste anywhere. Keys are never printed — only the prefix, enough to tell test from live. Environment variables are reported by name only; no value is ever included. That is deliberate, so the output can go straight into a public support thread or to an AI assistant without a redaction pass first.

vonpay checkout listen​

Watch your webhook delivery attempts in real time — a live tap on the delivery stream for the authenticated merchant. To drive a local handler during development, send it a signed test event with vonpay checkout trigger. This command requires a secret key (vp_sk_*); publishable keys are rejected by the server.

vonpay checkout listen

# Only payment events
vonpay checkout listen --events charge.succeeded --events charge.failed
FlagDescription
--eventsOnly stream attempts for the given event type. Repeat the flag for multiple types
--jsonEmit one JSON object per line on stdout instead of the colored transcript
--api-keyOverride the API key resolved from env / config

With a live key (vp_sk_live_*), a person confirms at the terminal before the stream opens, because live payment events reach your terminal (Live keys).

A test key shows only test-mode deliveries and a live key only live-mode ones. A test event sent to one of your webhook subscriptions shows on a test key's stream.

The stream needs the live webhook feed to be on for your API host. From 0.22.1, listen stops with exit code 1 instead of retrying for ever:

  • at once, when the server answers 501 (the feed is switched off on that server);
  • after three 503 answers in a row before the stream has opened. The message quotes the server's reason when it gives one.

Once the stream has opened, a 503 is a short outage and listen tries again, waiting as long as the server's Retry-After asks (at most 30 seconds).

vonpay checkout health​

Check the API health status.

vonpay checkout health

# JSON output
vonpay checkout health --json

--json output​

From 0.19.0 every --json answer is cleaned the same way, on every command, listen's lines included:

  • Removed from every key and value: hidden characters (such as a bidi override), escape sequences and control characters. A value's tabs, line feeds and carriage returns stay. U+2028 and U+2029 become a space.
  • Secret-shaped text in a value is blanked, for example to sk_*** or whsec_***. This is a safety net, not a guarantee: a real secret directly after a letter or digit (xsk_live_…) is not matched.
  • Two changes you may see in an ordinary value: an emoji's variation selector is removed, so ❤️ reads ❤. A secret's shape after _ or - is blanked, so order_sk_live_1 reads order_sk_***. Do not match on such a value.
  • Nothing is cut, and numbers stay numbers. If two keys become the same once cleaned, both stay: the later one reads name#2.

Two values are not blanked, because handing them back is the command's job: clientSecret with --show-secrets (by that key only, so the same secret anywhere else in the answer stays masked), and doctor --json's apiKeyPrefix, already masked to 4 characters of the key.

Error JSON goes through the same cleaner. It stays on one line and is cut at 2,000 characters.

Processor detail​

From 0.21.0, on payment-intents get, create, capture, void and list, --json leaves out by default:

  • the card processor's own answer to a decline (processorResponse), which is untrusted text;
  • the full record of each try (attempts, with each connection's name);
  • the card's first six digits: the card prints as { brand, last4 }, and the payment connection as { id } only.

Output you put in a log, a ticket or an AI tool then does not carry them by accident. list --json prints each payment's tries as a summary instead: attempts with only connectionId, result, declineCode and outcome, and attemptsStatus. Count tries only when attemptsStatus is complete. A value that does not look like a code or a connection id prints as [unrecognised value withheld].

--include-processor-detail prints everything as the API sent it, the connection's name included. The output then carries untrusted processor text: do not log it unmasked, put it in a ticket, or give it to an AI tool or the buyer. --include-metadata alone does not. The flag needs --json: without it, the command is refused before anything is sent.

Audit log​

From 0.18.0 the CLI writes one line per command to ~/.vonpay/audit/cli-YYYY-MM-DD.jsonl (UTC date), so you can review after an incident what was run on this machine, by a person, a script or an AI agent. It is on by default.

  • What a line holds: the time, the command, the key's mode and a short fingerprint of the key, the outcome, the API's error code and request id, and for money commands the amount, currency and target id. From 0.22.0 a product change records the product id, the price and currency where it sets them, and for change-price whether --apply-to-existing was sent.
  • What it never holds: request bodies, metadata, notes, descriptions, URLs, emails, card data, idempotency keys or the command line.
  • Settings: VONPAY_AUDIT_DIR moves the folder. VONPAY_AUDIT_LOG=off turns the log off. Files older than VONPAY_AUDIT_RETENTION_DAYS (1 to 365, default 30) are deleted when a command starts.
  • key_mode is test, live, publishable_test, publishable_live or unknown (a prefix the CLI does not know). If you look for live lines, read unknown lines as live too.
  • A full day: a day's file holds at most 50 MiB (from 0.19.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.

The log stays on your machine. If it cannot be written, the CLI prints one warning and the command carries on.

Upgrading to 0.23.0​

Same @vonpay/checkout-node range as 0.22.0; nothing to change. The trigger samples carry vp_tx_id_source next to vp_tx_id. With @vonpay/checkout-node 4.13.0 or later installed, an order_total_mismatch error also prints what the order adds up to, and a mirror-line refusal prints the line to fix.

Upgrading to 0.22.1​

Same @vonpay/checkout-node range as 0.22.0. listen now stops when the live webhook feed is not available, instead of retrying for ever. A script that runs listen and waits for it should expect exit code 1 in that case.

Upgrading to 0.22.0​

Needs @vonpay/checkout-node 4.11.0. Nothing changes for existing commands.

New: subscription-products get and the product changes. When a business limits customer pauses, a refused customer pause now prints the longest pause it allows, in billing cycles, and the latest resume date.

Upgrading to 0.21.0​

Needs @vonpay/checkout-node 4.9.0. Check:

  • A script that reads payment-intents --json output: it no longer gets the processor detail. Add --include-processor-detail if it needs it.
  • list / summary --metadata: a value over 128 characters is now refused before anything is sent.

Upgrading to 0.19.0​

Needs @vonpay/checkout-node 4.7.0. Check:

  • A script that reads --json: read what the cleaning can change, and that --show-secrets now hands back the secret only under clientSecret.
  • payment-intents list --all stops at 10,000 payments in text mode too, unless you pass --max-items.
  • A reader of the audit log: key_mode can now be unknown, or a publishable type where it used to read live.

New: subscription-products list and terms.

Upgrading to 0.18.0​

Needs @vonpay/checkout-node 4.5.0. Changes that need action:

  • Local webhook tests use a new signing secret. trigger no longer signs with your API key. Pin one with --signing-secret or VONPAY_CLI_SIGNING_SECRET and give your local handler the same value (trigger). In a script or CI job, set VONPAY_CLI_SIGNING_SECRET once in the environment. Production deliveries are unchanged.
  • Live money commands need --idempotency-key. On a live key, payment-intents create, capture, void and refunds create refuse without it.
  • sessions create asks a person on a live key, and refuses with no interactive terminal.
  • A live refund by --transaction needs --session-id.
  • A live key to your own proxy needs --allow-custom-base-url on each command, as well as VONPAY_ALLOW_CUSTOM_BASE_URL=1.
  • payment-intents list --json leaves out your metadata. Add --include-metadata for every field.

New: payment-intents list and payment-intents summary, and the audit log. On a 409 subscription_customer_change_limit_reached, errors print the customer's next allowed change date.

Upgrading to 0.17.0​

Needs @vonpay/checkout-node 4.4.0 or later. New:

  • When payment-intents create is refused before any money moved, the error output prints Refused attempt recorded as: and the failed payment intent that records the attempt (The record of a refused charge). --json error output carries it as paymentIntentId. Nothing was charged. Send the corrected charge with a new --idempotency-key.
  • trigger can send merchant.card_testing_suspected (Card-testing alert) and the five subscription.* events (Subscriptions).

Upgrading to 0.16.0​

Needs @vonpay/checkout-node 4.3.0 or later. Nothing changes for a vp_sk_test_… or vp_sk_live_… key. New:

  • payment-intents create, get, capture and void print Network advice: when the card network gave advice about the card, and Retry after: when it named a wait. A missing line is not permission to retry (Decline handling).
  • A settle-only refusal prints the store order's facts: the charge asked for, the order's unpaid balance (on an amount mismatch, the amount to charge instead), and the order's currency, status and payment status.
  • A restricted key refusal prints what the key refused: Key limit:, Key limit amount:, Used in the last 24 hours: and Key limit currency:, or Fields this key may not send:. --json error output carries the same fields.
  • trigger samples for charge.* and payment_intent.* carry processor_connection: null, and the failure samples carry network_advice: null, so a handler that reads them sees the keys. A real event names the connection.
  • sessions create --json and sessions get --json print a session's client secret as vp_cs_<mode>_<id>_secret_***, so a log or a pasted output does not carry it. The text output never shows it. Add --show-secrets to print it in full.
  • Values from the server print on one line, with escape sequences and control characters removed.

Upgrading to 0.15.0​

Breaking for anything that runs a live key:

  • --confirm-live no longer confirms anything. On a live key, payment-intents create, capture, void, refunds create, trigger and listen ask a person at the terminal and refuse without one. Move automation to a sandbox key.
  • login and init no longer save a live key. Supply it through VON_PAY_SECRET_KEY. A live key an older version saved still works, with a warning; remove it with vonpay checkout logout.
  • --amount and --amount-to-capture take whole numbers in minor units only (1499, not 14.99).
  • A key that is not vp_sk_test_… or vp_sk_live_… is refused.
  • A live key is refused for a base URL that is not a Von Payments API host, unless VONPAY_ALLOW_CUSTOM_BASE_URL=1.

New: payment-intents get and refunds list. capture, void and refunds create now generate an idempotency key when you omit one.