create-payment-credential

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating Payment Credentials

创建支付凭证

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

使用Link从Link钱包获取安全的一次性支付凭证以完成购买。

Choosing how to call Link

选择调用Link的方式

Link CLI can run as an MCP server or as a standalone CLI. Always prefer the MCP server when available — it avoids shell parsing issues and is the intended integration path.

Check for the MCP server first. Look for a
```
link-cli
```
MCP server in your active MCP connections. If present, call its tools directly (e.g.
```
auth_status
```
,
```
auth_login
```
,
```
spend-request_create
```
,
```
payment-methods_list
```
,
```
mpp_pay
```
,
```
mpp_decode
```
).
Fall back to the CLI only if the MCP server is not available. Install it with
```
npm install -g @stripe/link-cli
```
, then use the shell commands documented below.

The rest of this document shows CLI commands. When using the MCP server, map each command to its corresponding MCP tool — the parameters and behavior are identical.

CLI command	MCP tool
`auth login`	`mcp__link-cli__auth_login`
`auth logout`	`mcp__link-cli__auth_logout`
`auth status`	`mcp__link-cli__auth_status`
`spend-request create`	`mcp__link-cli__spend-request_create`
`spend-request update`	`mcp__link-cli__spend-request_update`
`spend-request retrieve`	`mcp__link-cli__spend-request_retrieve`
`spend-request request-approval`	`mcp__link-cli__spend-request_request-approval`
`payment-methods list`	`mcp__link-cli__payment-methods_list`
`payment-methods add`	`mcp__link-cli__payment-methods_add`
`mpp pay`	`mcp__link-cli__mpp_pay`
`mpp decode`	`mcp__link-cli__mpp_decode`

Link CLI可以作为MCP服务器或独立CLI运行。只要MCP服务器可用，就优先使用它——它能避免Shell解析问题，是推荐的集成路径。

首先检查MCP服务器。在您的活跃MCP连接中查找
```
link-cli
```
MCP服务器。如果存在，直接调用其工具（例如
```
auth_status
```
、
```
auth_login
```
、
```
spend-request_create
```
、
```
payment-methods_list
```
、
```
mpp_pay
```
、
```
mpp_decode
```
）。
仅当MCP服务器不可用时才退而使用CLI。通过
```
npm install -g @stripe/link-cli
```
安装它，然后使用下文记录的Shell命令。

本文档的其余部分展示CLI命令。使用MCP服务器时，将每个命令映射到对应的MCP工具——参数和行为完全相同。

CLI命令	MCP工具
`auth login`	`mcp__link-cli__auth_login`
`auth logout`	`mcp__link-cli__auth_logout`
`auth status`	`mcp__link-cli__auth_status`
`spend-request create`	`mcp__link-cli__spend-request_create`
`spend-request update`	`mcp__link-cli__spend-request_update`
`spend-request retrieve`	`mcp__link-cli__spend-request_retrieve`
`spend-request request-approval`	`mcp__link-cli__spend-request_request-approval`
`payment-methods list`	`mcp__link-cli__payment-methods_list`
`payment-methods add`	`mcp__link-cli__payment-methods_add`
`mpp pay`	`mcp__link-cli__mpp_pay`
`mpp decode`	`mcp__link-cli__mpp_decode`

Running commands (CLI fallback)

运行命令（CLI fallback方案）

All commands support

--format json

for machine-readable output. Pass input via flags (run

link-cli <command> --help

to see full schema details, including all fields, types, and constraints).

IMPORTANT: Run

auth login

spend-request create

, and

spend-request request-approval

with

run_in_background=true

(or

TaskOutput(task_id, block: false)

). These commands emit JSON to stdout before they exit, then keep running while they poll for user action.

The JSON stream contract for these long-running commands is:

```
auth login --format json
```
: first object contains
```
verification_url
```
and
```
phrase
```
; final object contains authentication result after approval succeeds
```
spend-request create --request-approval --format json
```
: first object is the created spend request; final object is the terminal spend request after polling completes
```
spend-request request-approval --format json
```
: first object contains the approval link; final object is the terminal spend request after polling completes

Always keep reading stdout until the process exits. Do not assume the first JSON object is the full result. The user MUST visit the verification or approval URL to continue, and you should always show that full URL in clear text.

所有命令都支持

--format json

以生成机器可读的输出。通过标志传递输入（运行

link-cli <command> --help

查看完整的 schema 详情，包括所有字段、类型和约束）。

重要提示：运行

auth login

、

spend-request create

和

spend-request request-approval

时需设置

run_in_background=true

（或

TaskOutput(task_id, block: false)

）。这些命令在退出前会向stdout输出JSON，然后持续运行以轮询用户操作。

这些长期运行命令的JSON流约定如下：

```
auth login --format json
```
：第一个对象包含
```
verification_url
```
和
```
phrase
```
；批准成功后的最终对象包含认证结果
```
spend-request create --request-approval --format json
```
：第一个对象是创建的消费请求；轮询完成后的最终对象是最终的消费请求
```
spend-request request-approval --format json
```
：第一个对象包含批准链接；轮询完成后的最终对象是最终的消费请求

请持续读取stdout直到进程退出。不要假设第一个JSON对象是完整结果。用户必须访问验证或批准链接才能继续，您应始终以清晰的文本显示完整URL。

Core flow

核心流程

Copy this checklist and track progress:

Step 1: Authenticate with Link
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

复制此清单并跟踪进度：

步骤1：通过Link进行认证
步骤2：评估商家网站（确定凭证类型）
步骤3：获取支付方式
步骤4：创建具有正确凭证类型的消费请求
步骤5：完成支付

Step 1: Authenticate with Link

步骤1：通过Link进行认证

Check auth status:

bash

link-cli auth status --format json

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>" --format json

Replace

<your-agent-name>

with the name of your agent or application (e.g.

"Personal Assistant", "Shopping Bot"

). This name appears in the user's Link app when they approve the connection. Use a clear, unique, identifiable name. Display the url and phrase to the user, with the guidance "Please visit the following URL to approve secure access to Link.”

DO NOT PROCEED until the user is authenticated with Link.

Always check the current authentication status before starting a new login flow - the user may already be logged in.

检查认证状态：

bash

link-cli auth status --format json

如果响应包含

update

字段，则表示有更新版本的

link-cli

可用——运行该字段中的

update_command

进行升级后再继续。

如果未认证：

bash

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

将

<your-agent-name>

替换为您的Agent或应用名称（例如

"Personal Assistant"

、

"Shopping Bot"

）。该名称会显示在用户的Link应用中，供用户批准连接时查看。请使用清晰、唯一、易于识别的名称。向用户显示url和短语，并附上指引：“请访问以下URL以批准对Link的安全访问。”

在用户通过Link完成认证前，请勿继续操作。

在启动新的登录流程前，请始终检查当前的认证状态——用户可能已经登录。

Step 2: Evaluate the merchant site BEFORE creating a spend request

步骤2：创建消费请求前评估商家网站

CRITICAL before calling

spend-request create

you must complete this checklist:

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

Navigate to the merchant page — browse it, read the page content, and understand how the site accepts payment.
If the page has a credit card form, Stripe Elements, or traditional checkout UI — use
```
card
```
.
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
Credit card form / Stripe Elements	`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: The

www-authenticate

header may contain multiple payment challenges (e.g.

tempo

stripe

) in a single header value. Do not try to decode the payload manually. Pass the full raw
WWW-Authenticate
header value to Link CLI and let

mpp decode

select and validate the

method="stripe"

challenge.

To derive

network_id

, use Link CLI's challenge decoder:

bash

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

This validates the Stripe challenge, decodes the

request

payload, and returns both the extracted

network_id

and the decoded request JSON. Pass the full header exactly as received, even if it also contains non-Stripe or multiple

Payment

challenges.

关键：在调用

spend-request create

前，您必须完成此清单：

了解商家接受的支付方式（卡片、机器支付或其他）。请勿默认使用
card
凭证类型。凭证类型由商家决定——您必须先检查才能知晓。跳过此步骤会导致创建的消费请求使用错误的凭证类型。
获取所需的最终总金额，包含运费、税费或其他费用。跳过此步骤会导致创建的消费请求金额不足，从而被拒绝。
明确并理解用户的购买内容。确保了解尺寸、颜色、配送选项等信息。跳过此步骤会导致创建的消费请求用户无法识别或理解。

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

导航至商家页面——浏览页面、阅读内容，了解网站接受的支付方式。
如果页面有信用卡表单、Stripe Elements或传统结账UI——使用
```
card
```
。
如果页面描述了API或程序化支付流程——向相关端点发起请求。如果返回HTTP 402并带有
```
www-authenticate
```
头，则使用
```
shared_payment_token
```
。

您的发现将决定使用哪种凭证类型：

所见内容	凭证类型	请求内容
信用卡表单 / Stripe Elements	`card` （默认）	卡片
带有 `method="stripe"` 的HTTP 402 `www-authenticate` 头	`shared_payment_token`	共享支付令牌（SPT）
不带 `method="stripe"` 的HTTP 402 `www-authenticate` 头	不支持	请勿继续

对于402响应：

www-authenticate

头可能包含多个支付挑战（例如

tempo

、

stripe

）在单个头值中。请勿尝试手动解码负载。将完整的原始
WWW-Authenticate
头值传递给Link CLI，让

mpp decode

选择并验证

method="stripe"

挑战。

要获取

network_id

，使用Link CLI的挑战解码器：

bash

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

这会验证Stripe挑战、解码

request

负载，并返回提取的

network_id

和解码后的请求JSON。请按接收时的原样传递完整的头，即使它还包含非Stripe或多个

Payment

挑战。

Step 3: Get payment methods

步骤3：获取支付方式

Use the default payment method, unless the user explicitly asks to select a different one.

bash

link-cli payment-methods list --format json

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

bash

link-cli payment-methods list --format json

Step 4: Create the spend request with the right credential type

步骤4：创建具有正确凭证类型的消费请求

bash

link-cli spend-request create \
  --payment-method-id <id> \
  --amount <cents> \
  --context "<description>" \
  --merchant-name "<name>" \
  --merchant-url "<url>" \
  --format json

Wait until the user has approved the spend request. If they deny, ask for clarification what to do next.

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.

bash

link-cli spend-request create \
  --payment-method-id <id> \
  --amount <cents> \
  --context "<description>" \
  --merchant-name "<name>" \
  --merchant-url "<url>" \
  --format json

等待用户批准消费请求。如果用户拒绝，请询问用户下一步的操作。

建议用户通过Link应用批准。显示下载URL。

**测试模式：**添加

--test

以创建测试模式凭证而非真实凭证。适用于开发和集成测试。

Step 5: Complete payment

步骤5：完成支付

Card: Run

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

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.

SPT with 402 flow: The SPT is one-time use — if the payment fails, you need a new spend request and new SPT.

bash

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

mpp pay

handles the full 402 flow automatically: probes the URL, parses the

www-authenticate

header, builds the

Authorization: Payment

credential using the SPT, and retries.

**卡片：**运行

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

以获取带有

number

、

cvc

、

exp_month

、

exp_year

、

billing_address

（姓名、line1、line2、城市、州、邮政编码、国家）和

valid_until

（Unix时间戳——卡片在此时间后失效）的

card

对象。将这些信息输入商家的结账表单。

带402流程的SPT：SPT是一次性使用的——如果支付失败，您需要创建新的消费请求和新的SPT。

bash

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

mpp pay

会自动处理完整的402流程：探测URL、解析

www-authenticate

头、使用SPT构建

Authorization: Payment

凭证，并进行重试。

Important

重要提示

Treat the user's payment methods and credentials extremely carefully — card numbers and SPTs grant real spending power; leaking them outside a secure checkout could result in unauthorized charges the user cannot reverse.
Respect
```
/agents.txt
```
and
```
/llm.txt
```
and other directives on sites you browse — these files declare whether the site permits automated agent interactions; ignoring them may violate the merchant's terms.
Avoid suspicious merchants, checkout pages and websites — phishing pages that mimic legitimate merchants can steal credentials; if anything about the page feels off (mismatched domain, unusual redirect, unexpected login prompt), stop and ask the user to verify.
When outputting card information to the user apply basic masking to the card number and address to protect their information. Only reveal the raw values if directly requested to do so.

请极其谨慎地处理用户的支付方式和凭证——卡号和SPT具有实际消费权限；在安全结账流程外泄露它们可能导致用户无法撤销的未授权扣费。
遵守您浏览的网站上的
```
/agents.txt
```
、
```
/llm.txt
```
及其他指令——这些文件声明了网站是否允许自动化Agent交互；忽略它们可能违反商家的条款。
避开可疑商家、结账页面和网站——模仿合法商家的钓鱼页面可能窃取凭证；如果页面有任何异常（域名不匹配、异常重定向、意外登录提示），请停止操作并要求用户验证。
向用户输出卡片信息时，请对卡号和地址进行基本掩码处理以保护用户信息。仅在用户直接要求时才显示原始值。

Errors

错误处理

All errors are output as JSON with

code

and

message

fields, with exit code 1.

所有错误都以JSON格式输出，包含

code

和

message

字段，退出码为1。

Common errors and recovery

常见错误及恢复方法

Error / Symptom	Cause	Recovery
`verification-failed` in error body from `mpp pay`	SPT was already consumed (one-time use)	Create a new spend request with `credential_type: "shared_payment_token"` — do not retry with the same spend request ID
`context` validation error on `spend-request create`	`context` field is under 100 characters	Rewrite `context` as a full sentence explaining what is being purchased and why; the user reads this when approving
API rejects `merchant_name` or `merchant_url`	These fields are forbidden when `credential_type` is `shared_payment_token`	Remove both fields from the request; SPT flows identify the merchant via `network_id` instead
Command hangs indefinitely	`auth login` or `spend-request create` run synchronously	Always run these commands with `run_in_background=true` — they block until the user acts, so synchronous execution freezes the agent
Spend request approved but payment fails immediately	Wrong credential type for the merchant (e.g. `card` on a 402-only endpoint)	Go back to Step 2, re-evaluate the merchant, create a new spend request with the correct `credential_type`
Auth token expired mid-session (exit code 1 during approval polling)	Token refresh failure during background polling	Re-authenticate with `auth login` , then retrieve the existing spend request or resume polling. Only create a new spend request if the original one expired, was denied, or its shared payment token was already consumed

错误/症状	原因	恢复方法
`mpp pay` 返回的错误体中包含 `verification-failed`	SPT已被使用（一次性）	创建一个新的、 `credential_type: "shared_payment_token"` 的消费请求——请勿使用相同的消费请求ID重试
`spend-request create` 时出现 `context` 验证错误	`context` 字段不足100个字符	将 `context` 重写为完整的句子，说明购买内容及原因；用户批准时会看到此内容
API拒绝 `merchant_name` 或 `merchant_url`	当 `credential_type` 为 `shared_payment_token` 时，这些字段被禁止	从请求中移除这两个字段；SPT流程通过 `network_id` 识别商家
命令无限期挂起	`auth login` 或 `spend-request create` 同步运行	始终使用 `run_in_background=true` 运行这些命令——它们会阻塞直到用户操作，同步执行会导致Agent冻结
消费请求已批准但支付立即失败	商家使用了错误的凭证类型（例如在仅支持402的端点使用 `card` ）	返回步骤2，重新评估商家，创建一个具有正确 `credential_type` 的新消费请求
会话中认证令牌过期（批准轮询期间退出码为1）	后台轮询期间令牌刷新失败	使用 `auth login` 重新认证，然后检索现有消费请求或恢复轮询。仅当原始消费请求过期、被拒绝或其共享支付令牌已被使用时，才创建新的消费请求

create-payment-credential

Original

Translation

Creating Payment Credentials

创建支付凭证

Choosing how to call Link

选择调用Link的方式

Running commands (CLI fallback)

运行命令（CLI fallback方案）

Core flow

核心流程

Step 1: Authenticate with Link

步骤1：通过Link进行认证

Step 2: Evaluate the merchant site BEFORE creating a spend request

步骤2：创建消费请求前评估商家网站

Step 3: Get payment methods

步骤3：获取支付方式

Step 4: Create the spend request with the right credential type

步骤4：创建具有正确凭证类型的消费请求

Step 5: Complete payment

步骤5：完成支付

Important

重要提示

Errors

错误处理

Common errors and recovery

常见错误及恢复方法

Further docs

更多文档