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_*) |
--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 |
The three --mit-* flags are all-or-nothing: supply all three to attach a merchant-initiated-transaction block, or none.
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.
vonpay checkout refunds create --payment-intent vpi_test_abc123
| Flag | Required | Description |
|---|---|---|
--payment-intent | Yes | Payment intent ID to refund (vpi_*) |
--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 |
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 for live keys with iframe-vault providers) |
--metadata | Metadata key=value (repeat the flag for multiple pairs) |
--idempotency-key | Idempotency key for safe retries |
--json | Output raw JSON |
With a test key, omitting --provider-reference auto-mints a mock card token. With a live key, an iframe-vault provider requires a browser-minted vault token, so the server returns a 422 validation_error if neither --buyer-id nor --provider-reference is supplied.
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 session.succeeded --url http://localhost:3000/webhooks/vonpay
Supported events: session.succeeded, session.failed, payment_intent.succeeded, payment_intent.failed, payment_intent.cancelled, charge.refunded. Any other event name is rejected. See the full webhook event catalog for event payload shapes.
| Flag | Required | Description |
|---|---|---|
--url | Yes | The endpoint to deliver the test event to |
--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) |
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