[hiroTamada]

Summary

The API now accepts a second VGS card shape: spec.card_mode: "cvc_only" with spec.card carrying only cvc_alias, for a card the merchant already holds on file whose checkout asks only for the security code. card_mode defaults to full, and must match the card sent (a full card missing pan_alias is rejected, not treated as cvc_only).

This updates the CLI's text to cover both modes:

• VgsCardSpec in the cards create/cards update help adds card_mode?: "full" | "cvc_only" and marks pan_alias, exp_month, exp_year and last4 optional, required with full and rejected with cvc_only.
• The VGS checkout flow help explains when to use cvc_only, that the number fields are rejected even when empty, and that a cvc-only card fills only cvc and reports no last4.
• cards create gains a cvc-only example.
• The requested-state guidance no longer says authorize always sends a PAN alias.

No request handling changes. cards create --provider vgs --spec-file already forwards the spec as written, so cvc-only cards work with the current Go SDK.

Output

-o json now shows spec.card_mode for a cvc-only card. It was missing because the CLI's vault item output allowlist did not include it (the CLI filters the raw response, so the SDK version was not the cause). A full card's read omits card_mode, matching the API, and the help says an absent value means full. The human table view still has no card_mode row; adding one needs the Go SDK bump to 0.143.0, which is otherwise a drop-in for the CLI.

Tests

• TestVaultVgsCVCOnlyCardSendsOnlyTheCVCAlias: the request body carries card_mode: "cvc_only" and a card object containing only cvc_alias; -o json shows card_mode; the alias never appears in output.
• TestVaultSpecHelpAndFlags asserts the new type fields and guidance.
• go vet ./... and go test ./... pass.

---

Note

Low Risk
Doc, display filtering, and test updates only; VGS create already forwards specs unchanged.

Overview
Updates the vaults CLI for the API's spec.card_mode: "cvc_only" VGS shape: help, checkout flow text, and VgsCardSpec now describe full vs cvc_only (CVC alias only when the merchant already has the card on file), validation rules (PAN/expiry/last4 rejected on cvc_only), and that fill/authorize behave differently for cvc-only cards.

Adds a cards create example for saved-card checkout, tweaks fill and requested-state guidance, and includes spec.card_mode in the -o json vault item allowlist so cvc-only items show the mode (full reads still omit it per API).

Adds TestVaultVgsCVCOnlyCardSendsOnlyTheCVCAlias and extends help/spec tests; no change to how --spec-file is forwarded.

^{Reviewed by Cursor Bugbot for commit b861062. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b861062. Configure here.}

[cursor]

New help uses Kernel not KERNEL

Low Severity

New VGS spec Long help names the product Kernel in Kernel cannot verify which card the merchant holds. Vaults user-facing copy uses KERNEL for the product name.

 

^{Triggered by learned rule: Vaults user-facing copy is lowercase; KERNEL for product}

^{Reviewed by Cursor Bugbot for commit b861062. Configure here.}

[yummybomb]

PR #313 review

1. vaults_help.go:246-247: the egress sentence leaves out the real risk. Use the
   API's wording: while the window is open, the proxy reveals the card's aliases
   to any destination, not only the CVC.
2. No card_mode row in the table, so a cvc-only card looks like a full card.
   Waiting on the SDK isn't needed: v0.143.0 has shipped, and printVaultItem
   (vaults_output.go:386) already has the raw JSON.
3. Nit, vaults_output.go:680: "or an expired card" doesn't fit cvc-only cards.

Verified: the help text matches the API, tests and CI pass.

Older issue, not from this PR (traced in code, not run): the API stores the error
message as status_reason, but the CLI matches on codes, so users probably see
only the generic declined text.