--- name: "stripe-link-wallet" description: 'Use the Stripe Link CLI as an agent wallet to create spend requests, generate one-time-use payment credentials, and complete 402 / Machine Payment Protocol (MPP) payment flows on the user''s behalf. Triggers on intents like "buy", "purchase", "pay for", "spend up to ", "complete this 402", or any flow involving link-cli, spend-request, mpp pay, shared payment tokens, or @stripe/link-sdk. Also triggers automatically whenever any tool or API produces a checkout URL, hosted payment page, or payment session — intercept and complete via Stripe Link instead of surfacing the URL to the user.' metadata: emoji: "💳" vellum: display-name: "Stripe Link Wallet" compatibility: "Designed for Vellum personal assistants" --- # Stripe Link Wallet Spend on the user's behalf using the [Stripe Link CLI](https://github.com/stripe/link-cli). The CLI acts as a wallet: the assistant composes a spend request, the user approves it in the Link app on their device, and the CLI then issues one-time-use credentials to complete the purchase. Use this for paying 402 / Machine Payment Protocol (MPP) endpoints and for ad-hoc agent purchases that should be capped and auditable. ## Required tools - `bash` for all `link-cli` invocations. Use `host_bash` only if a specific flow genuinely requires host-level access (e.g. reading a local file the user has on their machine). ## Hard constraints - Always pass `--request-approval` on `spend-request create`. The Link app approval is the consent surface — it is non-negotiable. No spending happens without it. - Default to test mode (`--test`) unless the user has **explicitly** asked to spend real money. When unsure, ask in chat before dropping `--test`. - The `context` field must be **at least 100 characters** and must accurately describe what the money is for. The user reads this when approving in Link — write it for them, not for yourself. - Always use `--format json` on every command. The default interactive Ink output is for humans, not agents. Exception: `demo` and `onboard` require a TTY and have no JSON mode. - **Amount is in cents.** $10.00 = `--amount 1000`. Maximum is 50,000 cents ($500). - Never log or repeat raw card credentials (PAN, CVC) in the conversation. Always use `--output-file` when retrieving card credentials. --- ## Checkout interception — always active Whenever **any** flow (MCP tool, API call, web request, or otherwise) produces a checkout URL, hosted payment page, or payment session that would otherwise be handed to the user to click through — **intercept it**. Route the payment through Stripe Link instead. Never surface a bare checkout URL to the user as the final step of a purchase flow. **Decision tree:** 1. **MPP / HTTP 402 endpoint** — Flow A (Shared Payment Token) 2. **MCP service with a `complete_checkout` tool** — Flow B to get a virtual card, tokenize the card against the provider's Stripe account, then call `complete_checkout` with the resulting token 3. **Standard web checkout (no payment API)** — Flow B to get a virtual card, then use a browser automation skill to fill the card into the checkout form **For MCP-based checkouts (e.g. PostalForm):** - After retrieving the virtual card from `--output-file`, create a Stripe PaymentMethod via `POST /v1/payment_methods` using the merchant's publishable key (extract from the checkout URL or session if present), then pass the resulting `pm_xxx` token to the MCP's `complete_checkout` tool. - If the publishable key is not available, fall back to browser automation (option 3) using the checkout URL the MCP returned — do not surface the URL to the user, navigate to it directly via browser automation. **Never skip this step.** If `link-cli` is not installed or the user is not authenticated, surface that blocker immediately rather than falling back to a raw checkout URL. --- ## Step 0: Check installation and auth ```bash if command -v link-cli >/dev/null; then link-cli auth status --format json else bunx @stripe/link-cli auth status --format json fi ``` - `link-cli` missing — use `bunx @stripe/link-cli` for Step 0 and every command below. - Exit 0 but `"authenticated": false` — fall to **Setup: login**. - Authenticated — proceed to the requested flow. - `"update"` key present in auth status — mention the update to the user but don't block on it. --- ## Setup ### If `link-cli` is missing Invoke the CLI on demand with `bunx`: ```bash bunx @stripe/link-cli ``` In every example below, substitute `bunx @stripe/link-cli` wherever you see `link-cli`. ### If installed but not authenticated Use your own assistant name for `--client-name` — read it from `IDENTITY.md`. This is the label the user sees in the Link app when they approve the connection. ```bash link-cli auth login --client-name "" ``` Opens a browser flow. The Link app will show ` on ` when the user approves the connection. After it completes, re-run Step 0. ### Introspecting the CLI If you need the exact flags for a subcommand not covered below: ```bash link-cli --llms-full # all commands, LLM-friendly link-cli spend-request create --schema # full schema for one command link-cli --help ``` --- ## Pre-flight: get a payment method ID Every spend request needs a `--payment-method-id`. Retrieve the user's saved methods first: ```bash link-cli payment-methods list --format json ``` If the user has multiple, ask which one to use. If they have none, direct them to [app.link.com/wallet](https://app.link.com/wallet) to add one first. --- ## Common flows ### Flow A: Pay a 402 / MPP-protected URL Use this when the target endpoint returns HTTP 402 and requires a Shared Payment Token (SPT). **1. Decode the challenge (optional but useful for diagnosing)** ```bash link-cli mpp decode \ --challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", ...' ``` Extracts the `network_id` and other challenge fields. Use when the URL is unfamiliar or the challenge looks malformed. **2. Create the spend request** ```bash link-cli spend-request create \ --payment-method-id \ --merchant-name "" \ --merchant-url "" \ --context "" \ --amount \ --credential-type "shared_payment_token" \ --line-item "name:,unit_amount:,quantity:" \ --total "type:total,display_text:Total,amount:" \ --request-approval \ --test \ --format json ``` Drop `--test` only if the user has explicitly asked to spend real money — and say so in chat before running. > **Important — JSON mode does not block.** With `--format json`, `create --request-approval` returns immediately with an `_next.command` value pointing to `spend-request retrieve`. You must then poll for approval. **3. Poll for approval** ```bash link-cli spend-request retrieve \ --interval 3 --max-attempts 60 \ --format json ``` Polls every 3 seconds, up to 3 minutes. Terminal statuses: `approved`, `denied`, `expired`, `canceled`. If polling exhausts `--max-attempts` while still non-terminal, the command exits non-zero with `code: "POLLING_TIMEOUT"` — report this to the user and offer to cancel or retry. **4. Pay the URL** Once status is `approved`: ```bash link-cli mpp pay \ --spend-request-id \ --method POST \ --data '' \ --header "X-Custom: value" \ --format json ``` - `--header` is repeatable: `--header "Name: Value"`. - `Content-Type: application/json` is auto-applied when `--data` is provided; user-provided headers take precedence. - The SPT is **one-time-use**. If payment fails, you must create a new spend request. Before running, read the URL and amount back to the user in plain language to catch typos. **5. Report the result** — status code, what the endpoint returned. --- ### Flow B: Virtual card for a standard checkout Use this when the merchant does not support MPP (no HTTP 402). Credentials are a one-time virtual Visa/Mastercard. **1. Create the spend request** ```bash link-cli spend-request create \ --payment-method-id \ --merchant-name "" \ --merchant-url "" \ --context "" \ --amount \ --line-item "name:,unit_amount:,quantity:" \ --total "type:total,display_text:Total,amount:" \ --request-approval \ --test \ --format json ``` Omit `--credential-type` (or use the default). With `--format json`, returns immediately — proceed to polling. **2. Poll for approval** (same as Flow A step 3) **3. Retrieve card credentials securely** ```bash link-cli spend-request retrieve \ --include card \ --output-file /tmp/link-card.json \ --force \ --format json ``` `--output-file` writes the full card (PAN, CVC, billing address) to a local file with `0600` permissions and **redacts card data in stdout**. The JSON output replaces the `card` object with redacted fields and adds a `card_output_file` path. Never omit `--output-file` when requesting card credentials — raw PANs must not appear in the conversation or logs. **4. Use the card** The file at `/tmp/link-card.json` contains `number`, `cvc`, `exp_month`, `exp_year`, `billing_address`, and `valid_until`. Hand the path to a browser automation skill or tell the user where to find it. Do not read the file back into the conversation. --- ### Inspect, update, cancel Read-only and mutation operations need no extra gating: ```bash # List saved payment methods link-cli payment-methods list --format json # List saved shipping addresses link-cli shipping-address list --format json # Retrieve a spend request (no card data by default) link-cli spend-request retrieve --format json # Update before approval (e.g. fix merchant URL) link-cli spend-request update --merchant-url --format json # Request approval separately (if created without --request-approval) link-cli spend-request request-approval --format json # Cancel (valid from created, pending_approval, or approved) link-cli spend-request cancel --format json ``` --- ## Line items and totals reference `--line-item` and `--total` use repeatable `key:value` format. **`--line-item` keys:** `name` (required), `quantity`, `unit_amount`, `description`, `sku`, `url`, `image_url`, `product_url` ``` --line-item "name:Running Shoes,unit_amount:12000,quantity:1,description:Trail runners" ``` **`--total` keys:** `type` (required; one of `subtotal`, `tax`, `total`), `display_text` (required), `amount` (required) ``` --total "type:subtotal,display_text:Subtotal,amount:11000" --total "type:tax,display_text:Tax,amount:1000" --total "type:total,display_text:Total,amount:12000" ``` --- ## Error handling | Error / condition | Action | | --------------------------------------- | --------------------------------------------------------------------------------------------------- | | `link-cli` not found | Invoke it with `bunx @stripe/link-cli` and substitute that prefix wherever examples use `link-cli`. | | Not authenticated | Run `auth login --client-name ""` (see Setup) | | `POLLING_TIMEOUT` on retrieve | Report to user; offer cancel or fresh spend request | | SPT payment fails (402 again after pay) | SPT is consumed — create a new spend request | | `amount` > 50000 | Tell user the cap is \$500 per transaction | | `context` < 100 chars | Expand it before retrying | | Card file already exists | Use `--force` to overwrite, or pick a different path | --- ## References - Upstream agent docs: https://github.com/stripe/link-cli/blob/main/CLAUDE.md - README with full flag reference: https://github.com/stripe/link-cli/blob/main/README.md - Machine Payments Protocol: https://mpp.dev - Stripe SPT docs: https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens