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:
- Environment variable
VON_PAY_SECRET_KEY(takes precedence) - 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,captureandvoid,refunds create,sessions create(from 0.18.0),triggerandlistenshow what they are about to do (the action, the amount, the idempotency key and the start of the key) and proceed only if you typeconfirm. 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,voidandrefunds createrefuse 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.
loginandinitrefuse a live key. Give it to the CLI for one session throughVON_PAY_SECRET_KEY. - A live key goes only to a Von Payments API host (
https://checkout.vonpay.comorhttps://checkout-staging.vonpay.com). To send it through a proxy you run, setVONPAY_ALLOW_CUSTOM_BASE_URL=1and also pass--allow-custom-base-urlon 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
| Flag | Required | Description |
|---|---|---|
--amount | Yes | Amount in minor units, a whole number (e.g. 1499 = $14.99) |
--currency | Yes | Three-letter currency code |
--country | No | Two-letter country code (e.g. US) |
--description | No | Session description |
--success-url | No | Redirect URL on success |
--cancel-url | No | Redirect URL on cancel |
--idempotency-key | No | Idempotency key for safe retries |
--dry-run | No | Validate without creating a session |
--json | No | Output raw JSON response, with the session's client secret masked |
--show-secrets | No | With --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
| Flag | Description |
|---|---|
--json | Output raw JSON response, with the session's client secret masked |
--show-secrets | With --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
| Flag | Required | Description |
|---|---|---|
--amount | Yes | Amount in minor units, a whole number (e.g. 1499 = $14.99) |
--currency | Yes | ISO 4217 currency code (e.g. USD) |
--capture-method | No | automatic (default) or manual (parks at authorized) |
--metadata | No | Metadata key=value (repeat the flag for multiple pairs) |
--mit-initiator | No | MIT initiator (merchant or customer) |
--mit-reason | No | MIT reason (recurring, unscheduled, or installment) |
--mit-original-transaction-id | No | Cardholder-initiated anchor payment intent ID (vpi_*) |
--payment-method | No | Stored card to charge (vp_pmt_*). Required for saved-card and recurring charges |
--session-id | No | Checkout session this charge belongs to (vp_cs_*). Refused if that session already charged |
--buyer-id | No | Your customer reference. Send it on every saved-card charge |
--buyer-email | No | Buyer email for this charge |
--idempotency-key | No (sandbox), Yes (live) | Key for this charge. Required on a live key. On a sandbox key, generated and printed when omitted |
--json | No | Output 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
| Flag | Description |
|---|---|
--json | Output JSON, without the processor detail |
--include-processor-detail | With --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
| Flag | Description |
|---|---|
--created-gte / --created-lt | The window: Unix seconds or an ISO 8601 time with a zone. At most 31 days |
--status, --outcome, --card-brand, --decline-code | Only these values, comma-separated |
--store | Only payments for this connected store hostname |
--metadata | Only payments with this one metadata tag, key=value. From 0.21.0 a value over 128 characters is refused before anything is sent |
--currency | Only payments in this currency |
--initiator | merchant (your charges on a saved card) or customer |
--limit | Page size, up to 100 (default 25) |
--starting-after | The cursor a previous run printed. Send exactly the same filters and window. It lasts 24 hours |
--all | Read every page, one request at a time |
--max-items | With --all, stop after this many payments. The default is 10,000, and reaching it prints a note on stderr |
--json | Output JSON. Each payment's status, outcome, amount, card, store and decline fields, and a summary of its tries, without your metadata |
--include-metadata | With --json, print every field, your metadata included, but not the processor detail |
--include-processor-detail | With --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:
| Flag | Description |
|---|---|
--group-by | Up to 3 of hour, day, week, store, metadata, card_brand, currency, outcome and decline_code, with one time unit |
--group-by-metadata-key | With --group-by metadata: the metadata key whose values become groups |
--time-zone | Where hours, days and weeks start (default UTC) |
--json | Output 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
| Flag | Description |
|---|---|
--amount-to-capture | Partial capture amount in minor units, a whole number (omit for a full capture) |
--idempotency-key | Idempotency key. Required on a live key. On a sandbox key, generated and printed when omitted |
--json | Output 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
| Flag | Description |
|---|---|
--idempotency-key | Idempotency key. Required on a live key. On a sandbox key, generated and printed when omitted |
--json | Output 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
| Flag | Required | Description |
|---|---|---|
--payment-intent | One of the two | Payment intent ID to refund (vpi_*) |
--transaction | One of the two | Transaction ID to refund (vp_tx_*): for a payment with no payment intent, or the transaction a refund_target_is_duplicate error names |
--amount | No | Refund amount in minor units, a whole number (omit for the full remaining balance) |
--currency | No | ISO 4217 currency code |
--reason | No | Free-form reason (mirrored back on the record) |
--metadata | No | Metadata key=value (repeat the flag for multiple pairs) |
--session-id | With --transaction on a live key | The checkout session the payment belongs to (vp_cs_*). The transaction must be that session's single payment |
--idempotency-key | No (sandbox), Yes (live) | Idempotency key. Required on a live key. On a sandbox key, generated and printed when omitted |
--json | No | Output 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
| Flag | Description |
|---|---|
--payment-intent | The payment's payment intent ID (vpi_*). Use this or --transaction |
--transaction | The payment's transaction ID (vp_tx_*) |
--limit | How many refunds to show: a whole number of at least 1 (default 25). The API allows at most 100 |
--starting-after | The next-page cursor printed by a previous run |
--json | Output 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
| Flag | Description |
|---|---|
--product-ref | Only the product with this reference, matched exactly |
--status | active or archived |
--limit | Page size, 1 to 100 (default 10) |
--starting-after | The id the previous run printed, for the next page |
--json | Output 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
| Flag | Description |
|---|---|
--amount | Read the terms for an intro first payment, in minor units, at or below the product's price |
--json | Output 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.
| Command | What it does |
|---|---|
create | A 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
| Flag | Description |
|---|---|
--idempotency-key | Required 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-label | Your 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-link | A 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. |
--json | Output 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
| Flag | Description |
|---|---|
--buyer-id | Buyer ID to attach the token to |
--provider-reference | Provider tokenization handle (required) |
--metadata | Metadata key=value (repeat the flag for multiple pairs) |
--idempotency-key | Idempotency key for safe retries |
--json | Output 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
| Flag | Description |
|---|---|
--json | Output 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.
| Flag | Required | Description |
|---|---|---|
--url | Yes | The 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-tunnel | No | Allow a non-local --url, such as an ngrok or Cloudflare Tunnel address |
--session-id | No | Use a specific session ID instead of a generated one |
--amount | No | Amount in minor units, a whole number (defaults to 1499) |
--currency | No | Currency code (defaults to USD) |
--signing-secret | No | Sign 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
| Flag | Description |
|---|---|
--json | Emit the bundle as JSON instead of the readable table |
--for-llm | Emit 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
| Flag | Description |
|---|---|
--events | Only stream attempts for the given event type. Repeat the flag for multiple types |
--json | Emit one JSON object per line on stdout instead of the colored transcript |
--api-key | Override 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
503answers 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_***orwhsec_***. 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, soorder_sk_live_1readsorder_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-pricewhether--apply-to-existingwas sent. - What it never holds: request bodies, metadata, notes, descriptions, URLs, emails, card data, idempotency keys or the command line.
- Settings:
VONPAY_AUDIT_DIRmoves the folder.VONPAY_AUDIT_LOG=offturns the log off. Files older thanVONPAY_AUDIT_RETENTION_DAYS(1 to 365, default 30) are deleted when a command starts. key_modeistest,live,publishable_test,publishable_liveorunknown(a prefix the CLI does not know). If you look forlivelines, readunknownlines 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
outcomeislog_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--jsonoutput: it no longer gets the processor detail. Add--include-processor-detailif 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-secretsnow hands back the secret only underclientSecret. payment-intents list --allstops at 10,000 payments in text mode too, unless you pass--max-items.- A reader of the audit log:
key_modecan now beunknown, or a publishable type where it used to readlive.
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.
triggerno longer signs with your API key. Pin one with--signing-secretorVONPAY_CLI_SIGNING_SECRETand give your local handler the same value (trigger). In a script or CI job, setVONPAY_CLI_SIGNING_SECRETonce in the environment. Production deliveries are unchanged. - Live money commands need
--idempotency-key. On a live key,payment-intents create,capture,voidandrefunds createrefuse without it. sessions createasks a person on a live key, and refuses with no interactive terminal.- A live refund by
--transactionneeds--session-id. - A live key to your own proxy needs
--allow-custom-base-urlon each command, as well asVONPAY_ALLOW_CUSTOM_BASE_URL=1. payment-intents list --jsonleaves out your metadata. Add--include-metadatafor 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 createis refused before any money moved, the error output printsRefused attempt recorded as:and the failed payment intent that records the attempt (The record of a refused charge).--jsonerror output carries it aspaymentIntentId. Nothing was charged. Send the corrected charge with a new--idempotency-key. triggercan sendmerchant.card_testing_suspected(Card-testing alert) and the fivesubscription.*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,captureandvoidprintNetwork advice:when the card network gave advice about the card, andRetry 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:andKey limit currency:, orFields this key may not send:.--jsonerror output carries the same fields. triggersamples forcharge.*andpayment_intent.*carryprocessor_connection: null, and the failure samples carrynetwork_advice: null, so a handler that reads them sees the keys. A real event names the connection.sessions create --jsonandsessions get --jsonprint a session's client secret asvp_cs_<mode>_<id>_secret_***, so a log or a pasted output does not carry it. The text output never shows it. Add--show-secretsto 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-liveno longer confirms anything. On a live key,payment-intents create,capture,void,refunds create,triggerandlistenask a person at the terminal and refuse without one. Move automation to a sandbox key.loginandinitno longer save a live key. Supply it throughVON_PAY_SECRET_KEY. A live key an older version saved still works, with a warning; remove it withvonpay checkout logout.--amountand--amount-to-capturetake whole numbers in minor units only (1499, not14.99).- A key that is not
vp_sk_test_…orvp_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.