我们正看到 stripe @link 成为一个面向智能体支付的开发者工具。（除了作为消费者钱包外，它还有一个CLI https://github.com/stripe/link-cli）如果您运营开发平台并希望提供智能体支付，我们可以帮助您以自定义方式将 Link 嵌入您的工具中。欢迎私信或给我发邮件。

stripe/link-cli

来源: https://github.com/stripe/link-cli

Link CLI

Link CLI 让智能体能够从 Link 钱包获取安全、一次性的支付凭证，以代您完成购买——无需存储您的真实卡详细信息。

该 CLI 可以生成两种凭证类型之一：

• 虚拟卡 (PAN)，用于标准的网页结账表单。签发的卡片可在任何地方使用，不仅限于支持 Link 的卖家或使用 Stripe 的卖家。
• 共享支付令牌 (Shared Payment Token) (https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens) (SPT)，当卖家接受通过机器支付协议 (Machine Payment Protocols) (https://mpp.dev) (MPP) 进行的程序化支付时使用。

目前，这仅对美国 Link 账户可用。

安装

npm i -g @stripe/link-cli

或使用 npx 直接运行：

npx @stripe/link-cli

与智能体配合使用

安装技能：

npx skills add stripe/link-cli

默认情况下，当从智能体（非 TTY）调用时，所有命令使用 toon 输出——一种紧凑、适合大语言模型的文本格式。所有命令都接受 --format [format] 参数以进行结构化输出。其他格式包括：json、yaml、md、jsonl。

列出可用命令：

link-cli --llms-full

使用 --schema 获取命令的完整架构。例如：

link-cli spend-request create --schema

MCP 服务器

Link CLI 可以作为本地 MCP 服务器运行。将以下内容添加到您的 MCP 客户端配置文件（如 .mcp.json）：

{
  "mcpServers": {
    "link": {
      "command": "npx",
      "args": ["@stripe/link-cli", "--mcp"]
    }
  }
}

HTTP MCP 服务器

使用 serve 可以通过 HTTP 将 link-cli 暴露为 MCP 端点。这对于无法启动本地子进程的远程或容器化智能体非常有用。

link-cli serve # 绑定到 127.0.0.1:54321（仅回环地址）
link-cli serve --port 8080
link-cli serve --host 0.0.0.0 # 暴露到非本地地址（请参阅下方警告）

服务器仅处理 /mcp 端点（以及 /.well-known/skills/ 发现）；任何其他路径都返回 404。默认绑定到 127.0.0.1，因此只有本机可以访问它。任何能访问该端口的人都可以使用此 CLI 的已认证 Link 会话，因此仅在可信的隔离网络上覆盖 --host——这样做会打印警告。

快速开始

运行引导式入门和演示流程：

link-cli onboard

登录

link-cli 需要一个 Link 账户。您可以登录现有账户或在线注册 (https://app.link.com)。

link-cli auth login

您将收到一个验证 URL 和一个短语。访问该 URL，登录您的 Link 账户，然后输入该短语以批准连接。

列出支付方式

link-cli payment-methods list

返回保存到您 Link 账户的银行卡和银行账户。在下一步中使用 id 字段作为 payment_method_id。

如果您没有支付方式，请在 Link (https://app.link.com/wallet) 中添加新的。

列出收货地址

link-cli shipping-address list

返回保存到您 Link 账户的收货地址。响应会保留 API 返回的可空字段 nickname、address 和地址字段。

创建支出请求

使用商户详情、商品行项目和金额创建支出请求。如果省略 --payment-method-id，将使用您的默认支付方式，如果未设置默认值，则使用第一个符合条件的支付方式：

link-cli spend-request create \
  --payment-method-id csmrpd_xxx \
  --merchant-name "Stripe Press" \
  --merchant-url "https://press.stripe.com" \
  --context "从 press.stripe.com 购买《公开工作》。用户通过购物助手发起了此购买。" \
  --amount 3500 \
  --line-item "name:Working in Public,unit_amount:3500,quantity:1" \
  --total "type:total,display_text:Total,amount:3500" \
  --request-approval

--request-approval 标志会触发向用户发送推送通知以进行批准，然后轮询直到请求被批准或拒绝。

使用 Link 应用 (https://link.com/download) 可以轻松批准请求。

如果创建的支出请求返回 status: "requires_action"，则尚无需批准——支付方式或账户需要先处理。请检查 status_details.requires_action.next_action 中的 type、display_message、action_url 和 resolution。

对于 3D Secure（resolution: "auto_resume"），请继续轮询 spend-request retrieve——一旦用户完成验证，请求会自行解决。

对于任何其他解决方案，请完成指示的操作并创建新的支出请求。

商品行项目和总金额

--line-item 和 --total 使用可重复的 key:value 格式。

--line-item 的键： name（必需）、quantity、unit_amount、description、sku、url、image_url、product_url

--line-item "name:Running Shoes,unit_amount:12000,quantity:1,description:Trail runners"

--total 的键： type（必需；可选值：subtotal、tax、total、items_base_amount、items_discount、discount、fulfillment、shipping、fee、gift_wrap、tip、store_credit）、display_text（必需）、amount（必需）

--total "type:subtotal,display_text:Subtotal,amount:12000" \
--total "type:total,display_text:Total,amount:12000"

审批详情

对于委托/预批准流程，传递 --approval-detail 并附上一个描述用户如何批准请求的 JSON 对象。必需字段：approved_at（unix 时间戳）、approval_method（click、programmatic 或 voice）、app_name、external_user_id。可选：ip_address、user_agent、device_type（mobile 或 web）、agent_log_id、external_user_name、external_session_id、authentication_method（biometric_face、biometric_fingerprint 或 passkey）。

在 CLI 模式下，作为 JSON 字符串传递：

link-cli spend-request create ... \
  --approval-detail '{"approved_at":1720000000,"approval_method":"click","app_name":"MyApp","external_user_id":"usr_123"}'

在 MCP/智能体模式下，作为结构化对象传递。

元数据

使用可重复的 --metadata 标志（key:value 格式）将任意字符串数据附加到支出请求。最多 50 个键，键长度 ≤ 40 个字符，值长度 ≤ 500 个字符。

link-cli spend-request create ... \
  --metadata "order_id:ord_123" \
  --metadata "team:growth"

在 MCP/智能体模式下，将 metadata 作为结构化的 { key: value } 对象传递。

凭证类型

默认情况下，支出请求会配置一张虚拟卡。对于支持机器支付协议 (https://mpp.dev) (HTTP 402) 和 Stripe 支付方式的商户，请改用 --credential-type "shared_payment_token"。

Link Pay Token

某些 Stripe 结账页面暴露了一个支持 Link Pay Token (LPT) 的 AI 智能体引导区块。在创建支出请求之前，请在浏览器中检查结账页面：启用智能体复选框，然后验证同一 Stripe 框架中是否存在 input[name="link_pay_token"] 和 data-stripe-merchant-account="acct_..."。

使用 DOM 派生的账户 ID 创建绑定 LPT 的请求。不要传递 --merchant-name 或 --merchant-url；Link 会从账户 ID 解析出规范的商户身份用于批准屏幕。

link-cli spend-request create \
  --payment-method-id csmrpd_xxx \
  --execution-method link_pay_token \
  --merchant-account-id acct_... \
  --context "从智能体检查的结账页面购买商品。用户通过购物助手发起了此购买。" \
  --amount 3500 \
  --request-approval

LPT 请求使用默认的 card 凭证类型，不支持 --test、--network-id 或 shared_payment_token。

获得批准后，在同一个结账页面使用之前，立即使用 --include link_pay_token 检索 LPT。每个返回的 LPT 有效期为 30 分钟，或直到支出请求过期。

如果任一 DOM 标记缺失，请改为创建常规虚拟卡支出请求；不要创建 LPT 请求。

执行支付

已批准的支出请求包含一个 card 对象，其中有 number、cvc、exp_month、exp_year、billing_address 和 valid_until。将这些信息输入商户的结账表单。

link-cli spend-request retrieve lsrq_001

默认情况下，检索支出请求不包括卡详细信息。传递 --include card 以查看未遮蔽的卡详细信息。

为避免将卡凭证泄露到智能体记录或日志中，请使用 --output-file 将完整卡信息写入安全的本地文件，同时标准输出仅显示遮蔽后的数据（品牌、后四位、有效期）：

link-cli spend-request retrieve lsrq_001 --include card --output-file /tmp/link-card.json --format json

文件以 0600 权限创建。如果文件已存在，除非传递 --force，否则命令会失败。

当设置了 --output-file 时，JSON 输出会用遮蔽后的字段替换 card 对象，并添加 card_output_file 路径。

对于智能体轮询，传递 --interval 和可选的 --max-attempts：

link-cli spend-request retrieve lsrq_001 --interval 2 --max-attempts 300

仅当请求达到终态（如 approved、denied、expired 或 canceled）后，轮询才会成功退出。

如果状态变为 requires_action，行为取决于 next_action.resolution：auto_resume（用于 3D Secure）意味着轮询会自动继续——一旦用户完成验证，请求会自行解决。任何其他解决方案会立即停止轮询，命令退出并显示 next_action 详情，而不是等待终态；调用者必须让用户执行操作，然后创建新的支出请求。

如果达到 --timeout 或 --max-attempts 而请求仍处于非终态，命令将以非零退出码退出，错误码为 code: "POLLING_TIMEOUT"，这样调用者就不会将仍待处理的请求视为完成。

如果商户支持 MPP，请改用 link-cli mpp pay：

link-cli mpp pay https://climate.stripe.dev/api/contribute \
  --spend-request-id lsrq_001 \
  --method POST \
  --data '{"amount":100}'

高级用法

认证

link-cli auth login --client-name "Claude Code" # 标识正在连接的智能体
link-cli auth login --client-name "Claude Code" --interval 5 --timeout 300 # 在一次调用中登录并轮询
link-cli auth upgrade --scope "userinfo:read spend_requests:approve" # 扩展访问权限到超集
link-cli auth status # 检查认证状态
link-cli auth logout # 断开连接

当您提供 --client-name 时，Link 应用在您批准连接时会显示它——例如，在 my-macbook 上显示 Claude Code 而不是 link-cli。

使用 --interval，登录命令会立即返回验证码，然后内联轮询直到认证或超时——无需单独的 auth status 调用。这对于无法在单独的轮询命令阻塞其 I/O 通道时中继代码的智能体是推荐的。

auth upgrade 接受与 auth login 相同的标志，但用于在已登录时扩展访问权限。与 auth login（当存在有效会话时会停止并显示“已登录”消息）不同，auth upgrade 会将您传递的标志与您当前被授予的 scope 和 authorization_details 合并，并为超集启动新的批准，因此您永远不会意外地丢失访问权限。如果没有有效会话，它会打印警告并仅使用您请求的访问权限继续。您当前的会话在整个批准过程中保持有效，只有在您批准新会话后才会被替换（旧的授权被撤销）——因此放弃批准会保持您现有的会话不变。

auth status 报告当前会话被授予的 scope 和 authorization_details（由令牌端点在登录/刷新时回显并存储在凭证文件中），并在有新版本可用时包含一个 update 字段：

{
  "authenticated": true,
  "scope": "userinfo:read payment_methods.agentic",
  "authorization_details": [{
    "type": "source",
    "actions": ["read"]
  }],
  "update": {
    "current_version": "0.1.2",
    "latest_version": "0.2.0",
    "update_command": "npm install -g @stripe/link-cli"
  }
}

scope 和 authorization_details 仅在令牌端点返回它们时才存在。设置 NO_UPDATE_NOTIFIER=1 以抑制更新检查（例如，在 CI 中）。

所有命令都接受 --auth <path> 以将认证凭证存储在特定文件中，而不是默认位置。auth login 写入此文件；所有其他命令从中读取。这对于使用单独身份运行多个会话很有用。

支出请求生命周期

支出请求经历：创建 → 请求批准 → 已批准（带有凭证）。

常规卡创建的必需字段： merchant_name、merchant_url、context 和 amount。payment_method_id 是可选的——如果省略，将使用您的默认支付方式，如果未设置默认值，则使用第一个符合条件的支付方式。

共享支付令牌请求则需要 network_id；Link Pay Token 请求需要 execution_method=link_pay_token 和 DOM 派生的 merchant_account_id，Link 会提供它们的规范商户身份。

约束： context 必须至少 100 个字符；amount 不得超过 50000（分）；currency 必须是 3 个字母的 ISO 代码。

用户在请求批准后有 10 分钟时间批准。已批准的凭证（卡或 SPT）自支出请求创建起 12 小时内有效。

测试模式： 传递 --test 以创建测试模式的支出请求。测试模式的支出请求将返回测试支付凭证（例如测试卡 4000009990001984），而不是真实的支付凭证。测试模式支出请求不会扣取支出请求的基础支付方式。这对于开发和集成测试而无需真实支付方式非常有用。

# 在批准前更新
link-cli spend-request update lsrq_001 \
  --merchant-url https://press.stripe.com/working-in-public

# 单独请求批准（代替 create --request-approval）
link-cli spend-request request-approval lsrq_001

# 随时检索（批准后包含卡凭证）
link-cli spend-request retrieve lsrq_001

# 取消支出请求（从 created、pending_approval 或 approved 状态）
link-cli spend-request cancel lsrq_001

限制

MPP

使用 mpp pay 完成在支持机器支付协议 (https://mpp.dev) 的商户上的购买。支出请求必须使用 credential_type: "shared_payment_token"，且您必须在支付前批准它。SPT 是一次性的——如果支付失败，请创建新的支出请求。

link-cli mpp pay https://climate.stripe.dev/api/contribute \
  --spend-request-id lsrq_001 \
  --method POST \
  --data '{"amount":100}' \
  --header "X-Custom: value"

使用 mpp decode 验证原始的 WWW-Authenticate 头并提取 shared_payment_token 支出请求所需的 network_id：

link-cli mpp decode \
  --challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", intent="charge", request="..."'

报告结果

使用 report 记录购买尝试的结果。报告是可选的，但在尝试后（无论成功或失败）调用它有助于 Stripe 为智能体改进结账体验。

# 成功购买
link-cli report --domain shop.example.com --outcome success --spend-request-id lsrq_abc123

# 被 captcha 阻止（例如）