@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+.

Login

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.

Commands

All commands are namespaced under vonpay checkout:

| Command | Purpose | |---|---| | vonpay checkout login | Save API key to ~/.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, session.expired, refund.created) | | 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.

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

• CLI reference
• API reference
• Quickstart

License

MIT