创建支付凭证

使用 [Link](https://link.com) 从 Link 钱包获取安全的一次性支付凭证，完成购买。

CLI 工具可生成以下两种凭证类型之一：

• 虚拟卡（PAN），适用于标准网页结账表单。发行的卡片可在任何地方使用。
• 共享支付令牌（SPT），当商家属于 Stripe 网络并支持程序化支付时使用（例如通过机器支付协议）。

安装

使用 npm install -g @stripe/link-cli 安装。或直接运行 npx @stripe/link-cli。

运行命令

Link CLI 可以作为 MCP 服务器 或 独立 CLI 运行。

MCP： 将以下内容添加到你的 MCP 客户端配置文件（如 .mcp.json 等）中：

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

直接运行 MCP 服务器：npx @stripe/link-cli@latest --mcp。

运行 tools/list 查看所有可用的 MCP 工具。

常用命令/选项

• 列出所有命令：link-cli --llms
• 列出所有命令及其参数：link-cli --llms-full
• 使用 --schema 获取特定命令的完整参数结构。例如：link-cli spend-request create --schema
• 多步骤命令会返回一个 _next 操作。例如，认证或创建支出请求后会返回 _next.command，必须执行该命令以完成流程。
• 默认输出格式为 toon。可通过 --format [json|md|yaml] 更改输出格式。
• 某些命令会返回验证或审批链接。这些链接必须清晰地展示给用户以供操作。
• 使用 --auth <path> 标志将认证凭据存储在指定文件中，而非默认位置。auth login 会写入此文件；其他命令则从中读取。示例：link-cli auth login --auth credentials.json

建议：运行 link-cli --llms 以了解所有可用命令。--llms-full 的输出是参数名称、类型和有效值的权威参考。在调用命令前使用 --schema 可了解其参数和约束。

核心流程

复制此检查清单并跟踪进度：

• 步骤 1：使用 Link 进行认证
• 步骤 2：评估商户网站（确定凭证类型）
• 步骤 3：获取支付方式
• 步骤 4：使用正确的凭证类型创建支出请求
• 步骤 5：完成支付

步骤 1：使用 Link 进行认证

检查认证状态：

link-cli auth status

如果响应包含 update 字段，说明有新版 link-cli 可用 —— 请运行该字段中的 update_command 升级后再继续。

若未认证：

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

将 <your-agent-name> 替换为你代理或应用的名称（例如 "个人助手"、"购物机器人"）。该名称会在用户使用 Link 应用批准连接时显示。请使用清晰、唯一且可识别的名称。

响应中包含一个 _next 命令 —— 必须运行它以轮询直到认证成功。如果环境无法在阻塞 I/O 的轮询命令期间传递验证码，请使用内联轮询：auth login --client-name "<name>" --interval 5 --timeout 300。此方式会立即返回验证码，并在同一命令中完成轮询。

在用户完成与 Link 的认证前，不得继续下一步。

每次启动新登录流程前，务必检查当前认证状态 —— 用户可能已登录。

步骤 2：在创建支出请求前评估商户网站

关键提示：在调用 spend-request create 之前，必须完成以下检查清单：

1. 明确商户接受付款的方式（信用卡、机器支付或其他）。不要默认使用 card 凭证类型。凭证类型由商户决定，必须先确认，不能仅凭猜测。跳过此步骤会导致创建错误类型的支出请求。
2. 确定最终所需金额。包括运费、税费及其他费用。跳过此步骤可能导致支出请求金额不足，被拒绝。
3. 清晰理解用户正在购买的商品。确保知晓尺寸、颜色、配送选项等信息。跳过此步骤可能导致用户不认可或无法理解支出请求。

确定商户的支付接受方式：

1. 访问商户页面 —— 浏览页面，阅读内容，理解其支付流程。
2. 如果页面包含信用卡表单、Stripe Elements 或传统结账界面 —— 使用 card。
3. 如果页面描述了 API 或程序化支付流程 —— 向相关接口发起请求。若返回 HTTP 402 且包含 www-authenticate 头部，则使用 shared_payment_token。

根据所见内容决定使用哪种凭证类型：

对于 402 响应：www-authenticate 头部可能包含多个支付挑战（如 tempo、stripe）在同一个头值中。不要手动解析负载。将**完整的原始 WWW-Authenticate 头部值**传给 Link CLI，让 mpp decode 自动选择并验证 method="stripe" 挑战。

用于获取 network_id，使用 Link CLI 的挑战解码器：

link-cli mpp decode --challenge '<raw WWW-Authenticate header>'

该命令将验证 Stripe 挑战，解码 request 负载，并返回提取的 network_id 和解码后的请求 JSON。请原样传入完整头部，即使其中也包含非 Stripe 或多个 Payment 挑战。

步骤 3：获取支付方式及潜在配送地址

使用默认支付方式，除非用户明确要求选择其他方式。

link-cli payment-methods list

如果商户结账需要配送或收货地址，请获取用户保存的配送地址。除非用户另有指定，否则使用默认地址。

link-cli shipping-address list

第四步：创建带有正确凭证类型的支出请求

link-cli spend-request create \
  --payment-method-id <id> \
  --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 参数说明：** name（必填）、quantity、unit_amount、description、sku、url、image_url、product_url。可重复用于多个商品。

**--total 参数说明：** type（必填；可选值：subtotal、tax、total、items_base_amount、items_discount、discount、fulfillment、shipping、fee、gift_wrap、tip、store_credit）、display_text（必填）、amount（必填）。可重复（例如：小计 + 税费 + 配送费 + 总计）。

在支出请求状态仍为 created 或 pending_approval 时，不要继续支付。如果轮询返回 POLLING_TIMEOUT，请持续等待，或询问用户是否继续轮询。若用户拒绝，应询问下一步操作。若用户希望取消，请取消该支出请求：

link-cli spend-request cancel <id>

建议用户通过 [Link 应用](https://link.com/download) 进行确认。请显示下载链接。

测试模式： 添加 --test 参数可创建测试凭证而非真实凭证。适用于开发和集成测试。

第五步：完成支付

信用卡支付： 执行 link-cli spend-request retrieve <id> --include card 获取包含 number、cvc、exp_month、exp_year、billing_address（name、line1、line2、city、state、postal_code、country）以及 valid_until（Unix 时间戳 — 卡片在此时间后失效）的 card 对象。将这些信息输入到商户的结账表单中。

安全凭证传递： 为避免卡号等敏感数据泄露至日志或对话记录中，可添加 --output-file <path> 将完整卡片信息写入本地文件（权限设为 0600），而标准输出仅显示脱敏内容。使用 --force 可覆盖已有文件。示例：

link-cli spend-request retrieve <id> --include card --output-file /tmp/link-card.json --format json

SPT 与 402 流程： SPT 为一次性使用——若支付失败，需重新创建支出请求并获取新的 SPT。

link-cli mpp pay <url> --spend-request-id <id> [--method POST] [--data '{"amount":100}'] [--header 'Name: Value']

mpp pay 会自动处理完整的 402 流程：探测 URL，解析 www-authenticate 头部，使用 SPT 构建 Authorization: Payment 凭证，并进行重试。

重要提示

• 请将用户的支付方式、凭证及配送地址视为敏感信息——卡号和 SPT 具有实际支付权限；配送地址属于个人身份信息（PII）。向用户展示时，应遮蔽或缩写地址（如仅显示城市和邮编），除非用户主动要求查看完整信息。
• 遵守 /agents.txt 和 /llm.txt 等网站配置文件中的指令——这些文件定义了网站是否允许自动化代理访问；忽略它们可能违反商户条款。
• 避免访问可疑的商户、结账页面或网站——仿冒正规商户的钓鱼页面可能窃取凭证；若页面存在任何异常（域名不符、异常跳转、非预期登录提示），请立即停止并让用户核实。
• 向用户输出卡信息时，应对卡号和地址进行基础遮蔽以保护隐私。仅在用户直接要求时才提供原始数据。

限制条件

若支出请求创建后未在规定时间内发起审批，或用户未在 10 分钟内完成确认，则请求将过期。请创建新请求。不要无限轮询——若审批窗口即将结束且用户尚未响应，请及时告知用户。

错误处理

所有错误均以 JSON 格式输出，包含 code 和 message 字段，退出码为 1。

常见错误及恢复方法

创建支付凭证（Create Payment Credential）

错误与症状排查

更多文档

• MPP/x402 协议：https://mpp.dev/protocol.md, https://mpp.dev/protocol/http-402.md, https://mpp.dev/protocol/challenges.md
• 链接：https://link.com/agents
• Link App（用于账户管理）：https://app.link.com
• Link 支持（如用户需要帮助使用 Link）：https://support.link.com/topics/about-link