Package Exports

@vonpay/checkout-cli

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@vonpay/checkout-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@vonpay/checkout-cli

Command-line tools for developers integrating with Von Payments Checkout. Create test sessions, drive the discrete-lifecycle payment intent flow (create / capture / void / refund), manage saved-card tokens, inspect binder capabilities, trigger webhook events, and bootstrap local integration work.

Install

npm install -g @vonpay/checkout-cli

Requires: Node 20+.

Save your Von Payments API key once:

vonpay checkout login

Stores credentials at ~/.vonpay/config.json (mode 0600). Use a test-mode key (vp_sk_test_...) for local development. The CLI also reads VON_PAY_SECRET_KEY from the environment if set, which takes precedence over the saved config.

The key is stored in plaintext (owner-only 0600), so remove it before sharing or decommissioning a machine:

vonpay checkout logout

logout deletes the stored key (and the config file if nothing else remains). It does not unset VON_PAY_SECRET_KEY — if that environment variable is set it still takes precedence, so unset it to fully log out of the shell.

Commands

All commands are namespaced under vonpay checkout:

Command	Purpose
`vonpay checkout login`	Save API key to `~/.vonpay/config.json`
`vonpay checkout logout`	Remove the stored API key from `~/.vonpay/config.json`
`vonpay checkout init`	Scaffold a minimal checkout integration starter
`vonpay checkout sessions create`	Create a hosted-checkout session and print the URL
`vonpay checkout sessions get <id>`	Fetch session details
`vonpay checkout payment-intents create`	Create a discrete-lifecycle payment intent (server-driven flows, MIT)
`vonpay checkout payment-intents capture <id>`	Capture an authorized intent (full or partial)
`vonpay checkout payment-intents void <id>`	Void an authorized intent before capture
`vonpay checkout refunds create`	Refund a captured intent (full or partial)
`vonpay checkout tokens create`	Create a payment-method token for saved-card / MIT flows
`vonpay checkout capabilities`	Show what this merchant's binder supports
`vonpay checkout trigger <event>`	Trigger a synthetic webhook event against your local endpoint (`session.succeeded`, `session.failed`, `payment_intent.*`, `charge.refunded`)
`vonpay checkout listen`	Stream live webhook delivery attempts; optionally re-forward each to a local URL with `--forward-to`
`vonpay checkout health`	Check API health and latency
`vonpay checkout doctor`	Diagnose runtime + env + live API probe

Run vonpay checkout <command> --help for full flag reference.

listen --forward-to signs forwarded events with the v1 webhook scheme — a single x-vonpay-signature: t=<unix-seconds>,v1=<hex> header, with the HMAC-SHA256 computed over ${t}.${rawBody} and a fresh t stamped at forward time. There is no separate timestamp header. Verify them in your local handler with vonpay.webhooks.constructEvent(rawBody, signatureHeader, secret). For this local forward loop the signing secret is your API key; production deliveries are keyed by your per-endpoint signing secret (whsec_…). This is a known limitation of local forwarding — the platform exposes no per-subscription signing secret on the listen stream, so the forwarder cannot reproduce the production secret.

Common flags

--json on every read/write command for machine-readable output
--idempotency-key <key> on every mutating command for safe retries (pass the same key with the same body to get the same record back)
--metadata key=value (repeatable) on payment-intents create, refunds create, and tokens create. Keys and values are bounded to 256 characters; control characters are rejected.

Live-key safety

Mutating commands that are irreversible on a live key — payment-intents create, payment-intents capture, payment-intents void, and refunds create — refuse to run with a vp_sk_live_* key unless you pass --confirm-live. This mirrors the --confirm-cli-exposure pattern used by login. Test-mode keys (vp_sk_test_*) ignore the flag.

Quick start

# One-time setup
vonpay checkout login

# Hosted checkout — buyer redirects to a Vonpay-hosted page
vonpay checkout sessions create --amount 1499 --currency USD --country US

# Discrete lifecycle — server-driven flow with manual capture (fulfillment-on-ship)
vonpay checkout payment-intents create --amount 1499 --currency USD --capture-method manual
vonpay checkout payment-intents capture vpi_test_abc123
# or, before fulfillment:
vonpay checkout payment-intents void vpi_test_abc123

# Refund a succeeded intent
vonpay checkout refunds create --payment-intent vpi_test_abc123 --amount 500 --reason duplicate

# What does my binder support?
vonpay checkout capabilities

# Trigger a session.succeeded webhook against localhost:3000
vonpay checkout trigger session.succeeded --url http://localhost:3000/webhooks/vonpay

Merchant-initiated transactions (MIT)

For recurring billing, retry, or saved-card charges, pass all three MIT flags together:

vonpay checkout payment-intents create \
  --amount 1499 --currency USD \
  --mit-initiator merchant \
  --mit-reason recurring \
  --mit-original-transaction-id vpi_test_anchor_xxx

Check vonpay checkout capabilities first to verify MIT: yes for your binder.

Documentation

License

MIT