@vonpay/checkout-cli 0.14.0 → 0.15.0

package/README.md

@@ -12,15 +12,21 @@ npm install -g @vonpay/checkout-cli
 
 ## Login
 
-Save your Von Payments API key once:
+Save your sandbox API key once:
 
 ```bash
 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.
+Stores the key at `~/.vonpay/config.json` (mode `0600`). Only sandbox keys (`vp_sk_test_...`) are saved. **A live key (`vp_sk_live_...`) is never saved**: `login` refuses it. Supply a live key for one terminal session through the environment instead, for example:
 
-The key is stored in plaintext (owner-only `0600`), so remove it before sharing or decommissioning a machine:
+```bash
+read -rs VON_PAY_SECRET_KEY && export VON_PAY_SECRET_KEY   # paste the key at the silent prompt
+```
+
+`VON_PAY_SECRET_KEY` takes precedence over the saved config. A live key saved by an older version of the CLI still works, but every run that uses it prints a warning; run `vonpay checkout logout` to delete it. A key that does not start with `vp_sk_test_` or `vp_sk_live_` (a publishable key, another service's key) is refused by every command.
+
+The saved key is plaintext (owner-only `0600`), so remove it before sharing or decommissioning a machine:
 
 ```bash
 vonpay checkout logout
@@ -34,15 +40,17 @@ All commands are namespaced under `vonpay checkout`:
 
 | Command | Purpose |
 |---|---|
-| `vonpay checkout login` | Save API key to `~/.vonpay/config.json` |
+| `vonpay checkout login` | Save a sandbox API key to `~/.vonpay/config.json` (live keys are never saved) |
 | `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 get <id>` | Read a payment intent back — the first step whenever a payment's outcome was unclear |
 | `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 (`--payment-intent`) or a settled transaction (`--transaction`), full or partial — pass exactly one |
+| `vonpay checkout refunds list` | List one payment's refunds and its refund totals (`--payment-intent` or `--transaction`) |
 | `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`) |
@@ -59,10 +67,27 @@ Run `vonpay checkout <command> --help` for full flag reference.
 - `--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.
+- **Amounts are whole numbers in minor units** (the currency's smallest unit): `--amount 1499` is 14.99 USD, and 1499 JPY is ¥1499. `14.99`, `abc`, `-5` or `1e3` is refused before anything is sent (`--amount`, `--amount-to-capture`).
+
+### When a payment's outcome is unclear
+
+An error that says `Next action: reconcile`, or `Retry withheld`, means the payment may or may not have gone through. **Check the payment first**: read it back with `vonpay checkout payment-intents get <id>` for a charge, capture or void, `vonpay checkout refunds list --payment-intent <id>` (or `--transaction <id>`) for a refund, or `sessions get <id>` for a checkout session, and act only on what it shows. If you then retry, reuse the **same** `--idempotency-key` as the first attempt, never a new one: a new key is a new action and can charge or refund twice.
 
 ### 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`. Since 0.8.0 `trigger` does too: it signs its synthetic event with the loaded key and sends it to `--url` (this machine only, unless `--url-tunnel`), and a live-key signature on a made-up event is one a receiver would accept as genuine. `listen` has its own `--confirm-live` for the same reason. This mirrors the `--confirm-cli-exposure` pattern used by `login`. Test-mode keys (`vp_sk_test_*`) ignore the flag.
+Commands that move money or cannot be undone on a live key — `payment-intents create`, `payment-intents capture`, `payment-intents void`, `refunds create`, `trigger` (which signs its synthetic event with the loaded key) and `listen` (which shows live payment events and, with `--forward-to`, signs each with the live key) — **ask a person to confirm at the terminal** when the key is `vp_sk_live_*`. The command shows what it is about to do (the action, the payment intent or transaction, the amount where known, the idempotency key, the API host when it is not the default, the key's first characters) and proceeds only if you type `confirm`. Anything else cancels, and nothing is sent.
+
+With a live key and **no interactive terminal** (stdin and stdout must both be a terminal), these commands refuse. This is deliberate: scripts, CI jobs and AI agents driving a shell cannot confirm a live money action. Use a sandbox key (`vp_sk_test_*`) for automation. `--confirm-live` no longer confirms anything on these commands (a flag can be typed by whoever drives the shell); it is still accepted so it is not an error, and is hidden from `--help`. A program that fakes a terminal can still answer the prompt; the prompt stops ordinary scripted and agent use, it is not a wall against a program built to get around it.
+
+Sandbox keys (`vp_sk_test_*`) are never asked.
+
+The money commands always send an idempotency key: `--idempotency-key` when you pass one, otherwise a generated one printed to stderr before anything is sent. Reuse that value to retry the same action.
+
+**No live key on disk.** `login` and `init` refuse a live key (`init` used to write one to `.env` with `--force`). Give your app its live key through your deployment's secret store or environment.
+
+**A live key is only sent to a Von Payments API host** (`https://checkout.vonpay.com` or `https://checkout-staging.vonpay.com`). If `VONPAY_BASE_URL` or `baseUrl` in `~/.vonpay/config.json` points anywhere else, live-key commands refuse (before any confirmation is asked), and `doctor` skips its key-carrying probe and says why. For a proxy you run yourself, set `VONPAY_ALLOW_CUSTOM_BASE_URL=1`. That opt-in protects against a base URL someone else set; whoever controls your shell can set it too, which is why the money commands still need a person at the terminal and show the API host they will use. It is read from the real environment only (the CLI loads no `.env` file). Sandbox keys are not restricted, but a base URL with a user name or password in it, or one that is not a valid URL, is refused for every key.
+
+`trigger` and `listen --forward-to` never follow a redirect from your endpoint: a 3xx answer is reported as a failure, so the signed event is never re-sent somewhere else.
 
 ## Quick start