create-payment-credential

# Create Payment Credential Use [Link](https://link.com) to get secure, one-time-use payment credentials from a Link wallet to complete purchases. The CLI can produce one of two credential types: - A virtual card (PAN) for use with a standard web checkout form. The issued card works anywhere. - A Shared Payment Token (SPT) when the seller is in the Stripe Network and accepts payments programmatically (for example with Machine Payment Protocols). It can also create a Link Pay Token (LPT)-bound SpendRequest for a supported Stripe checkout surface. LPT is an execution mode for the card flow, not a third credential type. ## Installing Install with `npm install -g @stripe/link-cli`. Or run directly with `npx @stripe/link-cli`. ## Running commands Link CLI can run as an **MCP server** or as a **standalone CLI**. **MCP:** Add the following to your MCP client config (`.mcp.json`, etc.) ```json { "mcpServers": { "link": { "command": "npx", "args": ["@stripe/link-cli", "--mcp"] } } } ``` Run the MCP server directly with `npx @stripe/link-cli@latest --mcp`. Call `tools/list` to see all available MCP tools. ### Common commands/options - List all commands: `link-cli --llms` - List all commands with parameters: `link-cli --llms-full` - Get a command's exact schema with `--schema`. For example, `link-cli spend-request create --schema` - Multi-step commands return a `_next` action. For example, authenticating or creating a spend request returns a `_next.command` that must be run to complete the flow. Where a structured form is offered alongside it (`mpp pay` returns `_next.pay_argv`), prefer that and invoke it without a shell — see the security notes. - By default all output is in `toon` format. Pass `--format [json|md|yaml]` to change output format. - Some commands return a verification or approval URL. **These** must be presented to the user clearly for their action. - `--auth <path>` flag to store auth credentials in a specific file instead of the default location. `auth login` writes to this file; all other commands read from it. Example: `link-cli auth login --auth credentials.json` _Recommended_: Run `link-cli --llms` to understand all the available commands. The `--llms-full` output is the canonical reference for parameter names, types, and valid values. Pass `--schema` before invoking a command to understand its parameters and constraints. ## Core flow Copy this checklist and track progress: - Step 0: Decide whether merchant selection needs personalization - Step 1: Authenticate with Link for the whole task - Step 2: Evaluate merchant site (determine credential type) - Step 3: Get payment methods - Step 4: Create spend request with correct credential type - Step 5: Complete payment ### Step 0: Decide whether merchant selection needs personalization Respect a merchant the user explicitly names; do not retrieve financial insights to second-guess that choice. If the merchant is unspecified and the request involves personal shopping, repeat purchasing, "my usual," or choosing a preferred store, also use the `financial-insights` skill before selecting a merchant. Use `link-cli summaries list` for preference-based selection. Do not retrieve raw transactions unless summaries cannot answer the request and transaction-level data is genuinely needed. Examples: - "Order flour from Smith's Store" -> use Smith's Store without financial insights. - "Order some bulk flour" from a personal shopper -> use summaries to inform merchant selection. - "Order from my usual baking supplier" -> use summaries to identify the observed preference. Note that Financial Insights may not be available in the user's country, the user may not have any accounts to share, or the user may choose not to share their accounts. If this becomes evident post authentication, proceed without attempting to use Financial Insights commands. ### Step 1: Authenticate with Link for the whole task Before starting authentication, identify all Link capabilities needed for the whole task and request them together. When preference-based merchant selection is needed, include `read_link_transactions` and `read_external_transactions`. If already authenticated without either action, use `auth upgrade` for only the missing actions instead of starting another login. Check auth status: ```bash link-cli auth status ``` When authenticated, the response also reports the session's granted `scope` and `authorization_details` (when the token endpoint returned them). If the response includes an `update` field, a newer version of `link-cli` is available — run the `update_command` from that field to upgrade before proceeding. If not authenticated: ```bash link-cli auth login --client-name "<your-agent-name>" ``` When preference-based merchant selection is also needed: ```bash link-cli auth login \ --client-name "<your-agent-name>" \ --source-actions read_link_transactions \ --source-actions read_external_transactions ``` Replace `<your-agent-name>` with the name of your agent or application (for example, `"Personal Assistant"`, `"Shopping Bot"`). This name appears in the user's Link app when they approve the connection. Use a clear, unique, identifiable name. The response includes a `_next` command — run it to poll until authenticated. If your environment cannot relay the verification code while a separate polling command blocks I/O, use inline polling instead: `auth login --client-name "<name>" --interval 5 --timeout 300`. This yields the code immediately then polls in the same command. If the user's email is already known, save them time by adding it as the URL-encoded `fromEmail` query parameter to any `app.link.com` verification or action URL; preserve existing query parameters. DO NOT PROCEED until the user is authenticated with Link. Always check the current authentication status before starting a new login flow — the user might already be logged in. If the user is already authenticated but you need broader access (an additional `scope`, `--source-actions`, or `--authorization-detail`), use `auth upgrade` instead of `auth login`. It takes the same flags but, rather than stopping with an "already logged in" message, merges what you request with the current `scope`/`authorization_details` and starts a new approval for the superset — so existing access is never dropped. Check `auth status` first so you know what's already granted. The current session stays valid during the approval and is only replaced once the user approves the new one, so an abandoned upgrade leaves the existing session working. Optionally, before a purchase, run `link-cli user-info retrieve` to inspect any applicable spend limits and verification requirements. Finite limit values are cents, while `null` limit or remaining values mean unlimited. When `agent_wallet_verification_requirement.action_url` is present, direct the user there to complete the required action. ### Step 2: Evaluate the merchant site BEFORE creating a spend request **CRITICAL:** Before calling `spend-request create` you must complete this checklist: 1. Understand how the merchant accepts payments (cards or machine payments or other). **Do NOT** default to `card` credential type. The merchant determines the credential type — you cannot know it without checking first. Skipping this step will produce a spend request with the wrong credential type. 2. Have the final total amount needed. Inclusive of any shipping costs, taxes or other costs. Skipping this step will produce a spend request that does not cover the full amount needed, and will be rejected. 3. Clear context and understanding of what the user is purchasing. Be sure to know sizes, colors, shipping options, etc. Skipping this step will produce a spend request that the user does not recognize or understand. **Determine how the merchant accepts payment:** 1. **Navigate to the merchant page** — browse it, read the page content, and understand how the site accepts payment. 2. **If the checkout page includes the AI-agent steering block** (find the "I am an AI agent" checkbox, or the `.AiAgentPaymentSteering` container — visually hidden but present in the DOM, typically inside a Stripe iframe) — it may support the **Link Pay Token flow** (Step 5, "Link Pay Token" section). **Requires browser automation.** Before creating an LPT request, check the checkbox and verify that both `input[name="link_pay_token"]` and `data-stripe-merchant-account` appear in the same frame. Read the account ID from that attribute. If either marker does **not** appear, follow the block's on-page instructions and use `card` instead. Without browser automation, use `card`. 3. **If the page has a credit-card form and no AI-agent steering block** (no "I am an AI agent" checkbox / `.AiAgentPaymentSteering`) — use `card`. 4. **If the page describes an API or programmatic payment flow** — make a request to the relevant endpoint. If it returns **HTTP 402** with a `www-authenticate` header, use `shared_payment_token`. What you find determines which credential type to use: | What you see | Credential type | What to request | |---|---|---| | `.AiAgentPaymentSteering` block / "I am an AI agent" checkbox, and ticking it reveals both `input[name="link_pay_token"]` and `data-stripe-merchant-account` | (none needed) | Link Pay Token flow (else `card`) | | Credit-card form, no AI-agent steering block | `card` (default) | Card | | HTTP 402 with `method="stripe"` in `www-authenticate` | `shared_payment_token` | Shared payment token (SPT) | | HTTP 402 without `method="stripe"` in `www-authenticate` | not supported | Do not continue | **For 402 responses:** Use `mpp pay` — it handles the entire flow automatically (probes URL, parses challenge, picks payment method, creates spend request, gets approval, and pays). See Step 5. ### Step 3: Confirm payment method and potentially shipping addresses Link will automatically use the default payment method on the account. If the user explicitly asks to pay with a specific card or bank, use the list command to show available options. Note that not all of the user's payment methods might appear; this will filter on "agentic-ready" payment types. ```bash link-cli payment-methods list ``` If the merchant checkout requires a shipping or delivery address, fetch the user's saved shipping addresses. Use the default address unless the user specifies otherwise. ```bash link-cli shipping-address list ``` ### Step 4: Create the spend request with the right credential type For card and Shared Payment Token flows, use the command below. For Link Pay Token, do **not** create this generic request: follow the LPT instructions in Step 5 after you have read the merchant account ID from the checkout DOM. ```bash link-cli spend-request create \ --amount <cents> \ --context "<description>" \ --merchant-name "<name>" \ --merchant-url "<url>" \ --line-item "name:<product>,unit_amount:<cents>,quantity:<n>" \ --total "type:total,display_text:Total,amount:<cents>" \ ``` **`--line-item` keys:** `name` (required), `quantity`, `unit_amount`, `description`, `sku`, `url`, `image_url`, `product_url`. Repeatable for multiple items. **`--total` keys:** `type` (required; one of: `subtotal`, `tax`, `total`, `items_base_amount`, `items_discount`, `discount`, `fulfillment`, `shipping`, `fee`, `gift_wrap`, `tip`, `store_credit`), `display_text` (required), `amount` (required). Repeatable (e.g. subtotal + tax + shipping + total). Do not proceed to payment while the request is still `created` or `pending_approval`. If polling exits with `POLLING_TIMEOUT`, keep waiting or ask the user whether to continue polling. If they deny, ask for clarification what to do next. If the user wants to abort, cancel the spend request: ```bash link-cli spend-request cancel <id> ``` `spend-request retrieve <id> --interval 2` waits for the initial status to change when it is `created`, `pending_approval`, or `requires_action` with `auto_resume`. All other statuses, including `submitted` and unfamiliar API values, return immediately. A status change does not necessarily mean approval: inspect the returned status and retrieve again if it is still waiting. Recommend the user approves with the [Link app](https://link.com/download). Show the download URL. **Test mode:** Add `--test` to create testmode credentials instead of real ones. Useful for development and integration testing. Link Pay Token does not support test mode. **Approval details:** For delegated/pre-approved flows, pass `--approval-detail` as a JSON object (MCP/agent) or JSON string (CLI). Required fields: `approved_at` (unix timestamp), `approval_method` (`click`|`programmatic`|`voice`), `app_name`, `external_user_id`. Optional: `ip_address`, `user_agent`, `device_type` (`mobile`|`web`), `agent_log_id`, `external_user_name`, `external_session_id`, `authentication_method` (`biometric_face`|`biometric_fingerprint`|`passkey`). **Metadata:** Attach arbitrary string data with the repeatable `--metadata "key:value"` flag (CLI) or a `{ key: value }` object (MCP/agent). Max 50 keys, key ≤ 40 chars, value ≤ 500 chars. Example: `--metadata "order_id:ord_123" --metadata "team:growth"`. If the response has `status: "requires_action"`, read `status_details.requires_action.next_action` (`type`, `display_message`, `action_url`, `resolution`). Show `display_message` to the user; present `action_url` clearly if present. - If `resolution` is `auto_resume` (currently only `three_d_secure`), run the returned `_next.command` (poll `spend-request retrieve <id> --interval 2 --max-attempts 300`) yourself — do not create a new spend request. Polling returns when the status changes; inspect the result, which may be `approved`, `submitted`, or `succeeded`, once the user completes the bank's challenge. - Otherwise (`resolution` is `create_new_spend_request` or `create_new_spend_request_after_completion` — covers `ssn_verification`, `identity_verification`, `contact_support`, `select_payment_method`, `add_payment_method`, `update_payment_method`, `re_authorize`, `three_d_secure_retry`), have the user complete the indicated action, then create a **new** spend request — the old one will expire on its own. This same `requires_action` status can also appear later from `spend-request retrieve` in Step 5 — `update_payment_method`, `re_authorize`, and `three_d_secure_retry` only ever surface this way, and they all use `create_new_spend_request`. Apply the same `resolution`-based branching there. ### Step 5: Complete payment **Card:** Run `link-cli spend-request retrieve <id> --include card` to get the `card` object with `number`, `cvc`, `exp_month`, `exp_year`, `billing_address` (name, line1, line2, city, state, postal_code, country), and `valid_until` (Unix timestamp — the card stops working after this time). Enter these details into the merchant's checkout form. **Safe credential handoff:** To avoid leaking card data into transcripts or logs, add `--output-file <path>` to write the full card to a local file (created with `0600` permissions) while stdout shows only redacted data. Use `--force` to overwrite an existing file. Example: ```bash link-cli spend-request retrieve <id> --include card --output-file /tmp/link-card.json --format json ``` **SPT with 402 flow:** `mpp pay` handles the entire machine payment flow end-to-end. It probes the URL for a 402 challenge, parses the `www-authenticate` header to extract the network ID and amount, creates a spend request, gets user approval, retrieves the SPT, and pays. SPTs are one-time use. ```bash link-cli mpp pay <url> --context "<description>" [-X POST] [-d '<body>'] [-H 'Name: Value'] [--test] ``` The amount and currency are derived from the 402 challenge automatically. Pass `--amount` to override. `--context` is required (min 100 chars) — describe the purchase and rationale so the user understands what they are approving. The default payment method is used unless `--payment-method-id` is specified. The SPT is **one-time use** — if the payment fails, run `mpp pay` again (it will create a new spend request). **Pre-approved spend request:** If you already have an approved spend request with `credential_type: "shared_payment_token"`, pass `--spend-request-id <id>` to skip the creation/approval steps: ```bash link-cli mpp pay <url> --spend-request-id <id> [-X POST] [-d '<body>'] [-H 'Name: Value'] ``` **Link Pay Token:** Some checkout pages embed an AI-agent steering block (the `AiAgentPaymentSteering` component) that lets an agent pay with a Link Pay Token, using the consumer's saved card without handling card numbers. This flow requires browser automation. The block is visually hidden and may be inside a Stripe frame. Do not assume a fixed location: search the top document and Stripe frames for `.AiAgentPaymentSteering` or the "I am an AI agent" checkbox, and run the following steps in the frame that contains it. 1. Open the merchant checkout page and locate the steering block. 2. **Check the "I am an AI agent" checkbox** to reveal the block. Use a DOM-level `click()` because the control is keyboard-hidden: ```javascript document.querySelector('.AiAgentPaymentSteering input[type="checkbox"]').click(); ``` 3. **Confirm the bound token path is available before creating a SpendRequest.** Within a few seconds, the same frame must contain both `input[name="link_pay_token"]` and a `data-stripe-merchant-account="acct_..."` attribute on the steering block.