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)
Commands
vonpay checkout login
Interactively store your API key. The CLI prompts for your secret key and saves it to ~/.vonpay/config.json.
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.
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 smallest currency unit (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 |
# 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
vonpay checkout sessions get
Retrieve a session by ID.
vonpay checkout sessions get vp_cs_test_abc123
| Flag | Description |
|---|---|
--json | Output raw JSON response |
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 (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 | Key for this charge. Generated and printed when omitted |
--confirm-live | No | Required to proceed when the loaded key is vp_sk_live_* |
--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. 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.
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 (omit for a full capture) |
--idempotency-key | Idempotency key for safe retries |
--confirm-live | Required to proceed when the loaded key is vp_sk_live_* |
--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 for safe retries |
--confirm-live | Required to proceed when the loaded key is vp_sk_live_* |
--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 (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) |
--idempotency-key | No | Idempotency key for safe retries |
--confirm-live | No | Required to proceed when the loaded key is vp_sk_live_* |
--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.
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}. One difference matters: for this local trigger the signing secret is your API key, whereas production webhooks are signed with your endpoint's whsec_* secret. So a passing test confirms your signature-verification scheme is wired correctly — verify against your API key for the local trigger, and against the endpoint's whsec_* secret in production. See Webhooks → Test your handler for the full walkthrough.
vonpay checkout trigger charge.succeeded --url http://localhost:3000/webhooks/vonpay
Supported events: every charge.* and payment_intent.* event, refund.failed, mirror.order.created, session.succeeded and session.failed; any other name is rejected. session.succeeded and session.failed are delivered to a subscription that selects them, but carry no saved card or vp_tx_id, so fulfil 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 (defaults to 1499) |
--currency | No | Currency code (defaults to USD) |
--confirm-live | No | Required when the loaded key is vp_sk_live_*: the event is signed with that live key |
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. Optionally re-forward each event to a local URL so you can drive your handler during development. This command requires a secret key (vp_sk_*); publishable keys are rejected by the server.
vonpay checkout listen
# Stream and re-forward each event to a local handler
vonpay checkout listen --forward-to http://localhost:3000/webhooks/vonpay
| Flag | Description |
|---|---|
--forward-to | Local URL to receive a shadow copy of each delivered event (loopback only by default) |
--forward-to-tunnel | Allow non-loopback --forward-to URLs (for ngrok / Cloudflare Tunnel workflows) |
--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 |
--confirm-live | Acknowledge that the stream may surface production webhook attempts (required for vp_sk_live_* keys) |
With a live key (vp_sk_live_*), listen refuses to start unless you pass --confirm-live, since production webhook attempts would stream to your terminal.
The stream is served by an operator-controlled endpoint. When that endpoint is disabled, the server responds with 503 Service Unavailable and a Retry-After header — re-run after a short wait.
vonpay checkout health
Check the API health status.
vonpay checkout health
# JSON output
vonpay checkout health --json