Create Payment Credential

Create Payment Credential

Use Link to get secure, one-time-use payment credentials from a Link wallet to complete purchases.

The CLI can produce three 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).
• A Link Pay Token (LPT) for a supported Stripe payment surface.

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.)

{
  "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 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 1: Authenticate with Link for the whole task

Check auth status:

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:

link-cli auth login --client-name "<your-agent-name>"

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 balance eligibility, address, applicable spend limits, and verification requirements. The optional eligible_for_balance field says whether the user's balance is available for Agent Wallet usage. 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:

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.

link-cli payment-methods list

Only rename or clear a payment-method nickname when the user explicitly asks. Never infer that a nickname should change. If the target ID is not known, run payment-methods list first and identify the intended method using only its redacted details and existing nickname. Then use:

link-cli payment-methods update <payment-method-id> --nickname "Work card"

Pass --nickname "" to clear a nickname.

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.

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.

link-cli spend-request create \
  --amount <amount> \
  --currency <code> \
  --context "<description>" \
  --merchant-name "<name>" \
  --merchant-url "<url>" \
  --line-item "name:<product>,unit_amount:<amount>,quantity:<n>" \
  --total "type:total,display_text:Total,amount:<amount>"

Currency: Spend requests can be in any supported currency. Pass --currency as a 3-letter ISO 4217 code (e.g. usd, eur, gbp); it defaults to usd. Use the currency the merchant's checkout charges in rather than converting prices yourself. If the currency is not supported, the API rejects the request.

Amounts (--amount, unit_amount, and --total amounts) are integers in the currency's smallest unit (e.g. cents): 1999 is $19.99 USD or €19.99 EUR. Some currencies have no minor unit, so 1999 in jpy is ¥1,999.

--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:

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. 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, device_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:

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.

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:

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:

   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.

   const merchantAccountId = document
     .querySelector(
       '.AiAgentPaymentSteering [data-stripe-merchant-account]',
     )
     ?.getAttribute('data-stripe-merchant-account');

   If either marker is absent or merchantAccountId is empty, do not create an LPT request. Use the normal card flow instead.

4. Create the merchant-bound SpendRequest. Use the DOM-derived account ID; do not send --merchant-name or --merchant-url. Link resolves the canonical merchant identity before the consumer approves.

   link-cli spend-request create \
     --credential-type link_pay_token \
     --merchant-account-id <acct_...> \
     --payment-method-id <id> \
     --amount <amount> \
     --currency <code> \
     --context "<description>" \
     --line-item "name:<product>,unit_amount:<amount>,quantity:<n>" \
     --total "type:total,display_text:Total,amount:<amount>"

   Do not set --network-id or --test for an LPT request. Present the approval URL and wait for approval before retrieving a token.

5. Retrieve the token immediately before injecting it. Each returned LPT is valid for up to 30 minutes, or until the SpendRequest expires:

   link-cli spend-request retrieve <id> --include link_pay_token --format json

6. Inject the token into input[name="link_pay_token"] with the native value setter. Do not type it character by character:

   const input = document.querySelector('input[name="link_pay_token"]');
   Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')
     .set.call(input, token);
   input.dispatchEvent(new Event('input', { bubbles: true }));

7. Wait for the exchange and login to complete. The card form is replaced by a single saved card showing the consumer's email in the header. Then click the Pay/Submit button.

If it does not transition, stop -- do not loop. If injection is delayed, retrieve one fresh token and retry once. If the saved card does not replace the form, cancel the bound SpendRequest and create a new normal card request, or report blocked. Do not reuse the LPT at a different checkout surface.

Important notes for the Link Pay Token flow:

• The account ID is browser-provided input, not proof of merchant identity. Link resolves it server-side and shows canonical merchant identity to the consumer before approval.
• The controls are invisible to a human and may live in a Stripe frame -- operate them programmatically in the frame that contains the block.
• Card numbers are not needed -- the token authorizes payment directly using the consumer's saved card on file.
• The agent pays with the token, not an interactive Link login. If the checkbox is missing, a signed-in Link session may be showing the Link wallet instead of the card form; retry in a context not signed in to Link.
• A bound LPT request is not the fallback virtual-card request. If the marker is missing before creation, create a normal card SpendRequest instead.