@itpay/cli 2.0.20 → 2.0.22

package/dist/src/client/backend.js

@@ -35,8 +35,10 @@ export class BackendClient {
     createCheckout(input, idempotencyKey) {
         return this.http.post("/v1/checkouts", input, idempotencyKey ? { idempotencyKey } : undefined);
     }
-    getCheckoutPresentation(checkoutID, displayToken) {
+    getCheckoutPresentation(checkoutID, displayToken, locale) {
         const qs = new URLSearchParams({ display_token: displayToken });
+        if (locale)
+            qs.set("locale", locale);
         return this.http.get(`/v1/checkouts/${encodeURIComponent(checkoutID)}/presentation?${qs}`);
     }
     // --- Payment intents ---

package/dist/src/commands/buy.js

@@ -13,6 +13,7 @@ import { validateContext } from "../state/client_context.js";
 import { dispatchRender } from "../render/index.js";
 import { platformKeyForHost } from "../render/plan.js";
 import { ensureIdeImageAttach } from "../render/ide.js";
+import { localizeCardURL, normalizeCardLocale } from "../render/locale.js";
 import { buildAgentChatHandoff } from "../render/markdown.js";
 import { formatMoney } from "../render/output.js";
 import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
@@ -68,8 +69,10 @@ export async function runBuy(backend, config, options) {
     });
     const checkoutID = checkout.checkout.checkout_id;
     const displayToken = checkout.display_token;
+    const locale = normalizeCardLocale(options.locale);
     const checkoutURL = tokenizedCheckoutURL(checkout.checkout_url, displayToken, checkout.qr_payload);
-    const qrPNGURL = checkout.qr_png_url ? absolutePublicURL(config.baseURL, checkout.qr_png_url) : undefined;
+    const cardURL = localizeCardURL(absolutePublicURL(config.baseURL, checkout.card_url ?? fallbackCardURL(config.baseURL, checkoutID, displayToken)), locale);
+    const qrPNGURL = localizeCardURL(absolutePublicURL(config.baseURL, checkout.card_png_url ?? checkout.qr_png_url ?? fallbackCardPNGURL(config.baseURL, checkoutID, displayToken)), locale);
     const orderItems = cart.items.map((item) => ({
         title: item.title,
         quantity: item.quantity,
@@ -106,12 +109,14 @@ export async function runBuy(backend, config, options) {
         host: options.host,
         checkoutID,
         checkoutURL,
+        cardURL,
         displayToken,
         qrPayload: checkout.qr_payload,
         nextAction: checkout.checkout.next_action,
         orderItems,
         orderCurrency: checkout.checkout.currency,
         ...(options.agentType ? { agentType: options.agentType } : {}),
+        locale,
     };
     if (qrPNGURL)
         planInput.qrPNGURL = qrPNGURL;
@@ -138,7 +143,7 @@ export async function runBuy(backend, config, options) {
             displayToken,
             plan,
             waitStatus,
-            ...(qrPNGURL ? { qrPNGURL } : {}),
+            qrPNGURL,
             ...(paymentIntent ? { paymentIntent } : {}),
             ...(options.agentType ? { agentType: options.agentType } : {}),
             ...(options.target ? { target: options.target } : {}),
@@ -197,7 +202,7 @@ function buildBuyEnvelope(input) {
     }
     const presentationHandoff = buildCheckoutHandoff({
         platform,
-        url: input.checkoutURL,
+        url: input.plan.linkOnlyURL ?? input.checkoutURL,
         amount,
         plan: input.plan,
         ...(input.agentType ? { agentType: input.agentType } : {}),
@@ -213,7 +218,7 @@ function buildBuyEnvelope(input) {
         result,
         handoff: presentationHandoff.handoff,
         instruction: presentationHandoff.instruction,
-        next: { command: `itpay checkout --id ${input.checkoutID} --token ${input.displayToken} --json`, reason: "稍后查询同一笔 Checkout 状态" },
+        next: { command: input.plan.afterActionCommand ?? `itpay checkout --id ${input.checkoutID} --token ${input.displayToken} --json`, reason: "稍后查询同一笔 Checkout 状态" },
         recovery: [],
     };
 }
@@ -242,7 +247,7 @@ async function waitForPaymentSSE(backend, checkoutID, displayToken, timeoutSec)
 export function buildCheckoutQRPlan(input) {
     const summary = `Scan the QR or open ${input.checkoutURL} to start the human checkout flow.`;
     const isPayment = input.paymentIntentID != null;
-    const afterCommand = qualifyItPayCommand(`itpay checkout --id ${input.checkoutID} --token ${input.displayToken} --json`, input.agentType);
+    const afterCommand = qualifyItPayCommand(`itpay checkout --id ${input.checkoutID} --token ${input.displayToken}${input.locale === "en" ? " --locale en" : ""} --json`, input.agentType);
     const platform = {
         text: summary,
         links: [
@@ -262,6 +267,7 @@ export function buildCheckoutQRPlan(input) {
         host: input.host,
         summary,
         url: input.qrPayload,
+        ...(input.agentType?.trim().toLowerCase() === "workbuddy" && input.cardURL ? { linkOnlyURL: input.cardURL } : {}),
         preferredQRSources: [input.qrPNGURL ?? input.qrPayload],
         checkoutID: input.checkoutID,
         platform,
@@ -280,6 +286,13 @@ export function buildCheckoutQRPlan(input) {
         plan.paymentIntentID = input.paymentIntentID;
     return plan;
 }
+function fallbackCardURL(baseURL, checkoutID, displayToken) {
+    const root = baseURL.replace(/\/$/, "");
+    return `${root}/v1/checkouts/${encodeURIComponent(checkoutID)}/card?display_token=${encodeURIComponent(displayToken)}`;
+}
+function fallbackCardPNGURL(baseURL, checkoutID, displayToken) {
+    return `${fallbackCardURL(baseURL, checkoutID, displayToken)}.png`.replace("/card?", "/card.png?");
+}
 // --- contact field interaction ---
 function findMissingContactFields(contact, fields) {
     return fields.filter((field) => {

package/dist/src/commands/checkout.js

@@ -4,12 +4,14 @@ import { ensureIdeImageAttach } from "../render/ide.js";
 import { buildAgentChatHandoff } from "../render/markdown.js";
 import { platformKeyForHost } from "../render/plan.js";
 import { renderTerminalQR } from "../render/qr.js";
+import { localizeCardURL, normalizeCardLocale } from "../render/locale.js";
 import { DEFAULT_BASE_URL } from "../state/config.js";
 import { buildCheckoutQRPlan } from "./buy.js";
 import { buildCheckoutHandoff, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
 import { writeCommandEnvelope } from "./guidance.js";
 export async function runCheckoutPresentation(backend, options) {
-    const presentation = await backend.getCheckoutPresentation(options.checkoutID, options.displayToken);
+    const locale = normalizeCardLocale(options.locale);
+    const presentation = await backend.getCheckoutPresentation(options.checkoutID, options.displayToken, locale === "en" ? locale : undefined);
     const host = options.host ?? "terminal";
     if (!checkoutNeedsHumanHandoff(presentation.checkout.status)) {
         const envelope = terminalCheckoutEnvelope(presentation);
@@ -21,15 +23,18 @@ export async function runCheckoutPresentation(backend, options) {
         return;
     }
     const checkoutURL = checkoutPageURL(options.baseURL, options.checkoutID, options.displayToken);
-    const qrPNGURL = absolutePublicURL(options.baseURL, presentation.qr_png_url ?? checkoutQRPNGURL(options.baseURL, options.checkoutID, options.displayToken));
-    const nextCommand = `itpay checkout --id ${options.checkoutID} --token ${options.displayToken} --json`;
+    const cardURL = localizeCardURL(absolutePublicURL(options.baseURL, presentation.card_url ?? checkoutCardURL(options.baseURL, options.checkoutID, options.displayToken)), locale);
+    const qrPNGURL = absolutePublicURL(options.baseURL, presentation.card_png_url ?? presentation.qr_png_url ?? checkoutCardPNGURL(options.baseURL, options.checkoutID, options.displayToken));
+    const localizedPNGURL = localizeCardURL(qrPNGURL, locale);
+    const nextCommand = `itpay checkout --id ${options.checkoutID} --token ${options.displayToken}${locale === "en" ? " --locale en" : ""} --json`;
     const plan = buildCheckoutQRPlan({
         host,
         checkoutID: options.checkoutID,
         checkoutURL,
+        cardURL,
         displayToken: options.displayToken,
         qrPayload: checkoutURL,
-        qrPNGURL,
+        qrPNGURL: localizedPNGURL,
         nextAction: presentation.checkout.next_action,
         orderItems: presentation.items.map((item) => ({
             title: item.title,
@@ -62,7 +67,7 @@ function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, a
     const amount = formatMoney(presentation.checkout.amount_minor, presentation.checkout.currency);
     const presentationHandoff = buildCheckoutHandoff({
         platform,
-        url: checkoutURL,
+        url: plan.linkOnlyURL ?? checkoutURL,
         amount,
         plan,
         ...(agentType ? { agentType } : {}),
@@ -138,9 +143,13 @@ function checkoutPageURL(baseURL, checkoutID, displayToken) {
     const root = publicRoot(baseURL);
     return `${root}/checkout/${encodeURIComponent(checkoutID)}?display_token=${encodeURIComponent(displayToken)}`;
 }
-function checkoutQRPNGURL(baseURL, checkoutID, displayToken) {
+function checkoutCardURL(baseURL, checkoutID, displayToken) {
     const root = publicRoot(baseURL);
-    return `${root}/v1/checkouts/${encodeURIComponent(checkoutID)}/qr.png?display_token=${encodeURIComponent(displayToken)}`;
+    return `${root}/v1/checkouts/${encodeURIComponent(checkoutID)}/card?display_token=${encodeURIComponent(displayToken)}`;
+}
+function checkoutCardPNGURL(baseURL, checkoutID, displayToken) {
+    const root = publicRoot(baseURL);
+    return `${root}/v1/checkouts/${encodeURIComponent(checkoutID)}/card.png?display_token=${encodeURIComponent(displayToken)}`;
 }
 function publicRoot(baseURL) {
     return (baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");

package/dist/src/commands/checkout_handoff.js

@@ -7,13 +7,14 @@ export function isWorkBuddyPlainChat(agentType, platform) {
 }
 export function buildCheckoutHandoff(input) {
     const handoff = { url: input.url };
+    const workBuddyLinkOnly = isWorkBuddyPlainChat(input.agentType, input.platform);
     if (input.platform === "markdown") {
         if (input.localPath)
             handoff.qr_local_path = input.localPath;
         if (input.markdown)
             handoff.markdown = input.markdown;
     }
-    else if (input.platform === "plain_chat" && input.qrImageURL) {
+    else if (input.platform === "plain_chat" && input.qrImageURL && !workBuddyLinkOnly) {
         handoff.qr_image_url = input.qrImageURL;
     }
     else if (input.platform === "telegram" && input.qrImageURL) {
@@ -24,15 +25,12 @@ export function buildCheckoutHandoff(input) {
     }
     return {
         handoff,
-        instruction: checkoutHandoffInstruction(input.agentType, input.platform, input.amount, Boolean(input.qrImageURL)),
+        instruction: checkoutHandoffInstruction(input.agentType, input.platform, input.amount),
     };
 }
-function checkoutHandoffInstruction(agentType, platform, amount, hasQRImage) {
+function checkoutHandoffInstruction(agentType, platform, amount) {
     if (isWorkBuddyPlainChat(agentType, platform)) {
-        if (!hasQRImage) {
-            return `Backend 尚未确认付款，且本次没有返回可展示的二维码。向用户说明金额 ${amount} 并发送 handoff.url，然后停止等待。不要调用 present_files，不要检查本地文件，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
-        }
-        return `Backend 尚未确认付款。读取 handoff.qr_image_url 的完整字符串，原样作为 files 数组唯一元素调用 present_files({ files: ["<完整 qr_image_url>"] })；确认右侧二维码预览已打开后，向用户说明金额 ${amount} 并发送 handoff.url，然后停止等待。如果 present_files 失败，只发送 handoff.url 并说明二维码预览未打开，然后停止。不要检查本地文件，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        return `Backend 尚未确认付款。向用户说明金额 ${amount}，直接发送并打开 handoff.url，然后停止等待。不要调用 present_files，不要检查本地文件，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (platform === "markdown") {
         return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;

package/dist/src/commands/install.js

@@ -15,7 +15,7 @@ const INSTRUCTIONS = {
     "codex-cli": "在 Codex CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
     "claude-code-desktop": "在 Claude Code Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
     "claude-code-cli": "在 Claude Code CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
-    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。Checkout 返回 qr_image_url 时，按当次 instruction 调用 present_files 在右侧打开二维码，不要检查本地二维码文件。",
+    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。Checkout 只返回已渲染的付款 Card Link；直接打开 handoff.url，不要调用 present_files，也不要检查本地二维码文件。",
     "kimi-code": "保持 kimi-code Agent Type，使用标准 CLI 命令和终端付款交接；不要切换到其他平台身份。",
     openclaw: "保持 openclaw Agent Type；每个展示命令都从当前可信会话上下文显式传 --host，IM 入口同时传 --target。Telegram 使用返回的原生 message action，其他入口展示标准二维码和付款链接。",
 };

package/dist/src/commands/pay.js

@@ -20,10 +20,18 @@ function payEnvelope(intent, options) {
     const terminal = ["failed", "expired", "refunded"].includes(intent.status);
     const verified = intent.status === "verified" || intent.status === "partially_refunded";
     const handoff = {};
-    if (!terminal && !verified && intent.action?.qr_image_url)
-        handoff.qr_image_url = intent.action.qr_image_url;
-    if (!terminal && !verified && intent.action?.mobile_wallet_url)
-        handoff.mobile_wallet_url = intent.action.mobile_wallet_url;
+    const workBuddyLinkOnly = isWorkBuddyPlainChat(options.agentType, platformKeyForHost(options.host));
+    if (!terminal && !verified && workBuddyLinkOnly) {
+        const url = intent.action?.mobile_wallet_url ?? intent.action?.qr_image_url;
+        if (url)
+            handoff.url = url;
+    }
+    else {
+        if (!terminal && !verified && intent.action?.qr_image_url)
+            handoff.qr_image_url = intent.action.qr_image_url;
+        if (!terminal && !verified && intent.action?.mobile_wallet_url)
+            handoff.mobile_wallet_url = intent.action.mobile_wallet_url;
+    }
     const hasAction = Object.keys(handoff).length > 0;
     const amount = formatMoney(intent.amount_minor, intent.currency);
     return {
@@ -35,7 +43,7 @@ function payEnvelope(intent, options) {
             amount,
         },
         ...(hasAction ? { handoff } : {}),
-        instruction: payInstruction(options, verified, terminal, hasAction, Boolean(handoff.qr_image_url), Boolean(handoff.mobile_wallet_url), amount),
+        instruction: payInstruction(options, verified, terminal, hasAction, amount),
         next: {
             command: `itpay checkout --id ${options.checkoutID} --token ${options.displayToken} --json`,
             reason: verified ? "读取权威订单和履约状态" : "读取同一 Checkout 的权威付款状态",
@@ -43,7 +51,7 @@ function payEnvelope(intent, options) {
         recovery: [],
     };
 }
-function payInstruction(options, verified, terminal, hasAction, hasQR, hasWallet, amount) {
+function payInstruction(options, verified, terminal, hasAction, amount) {
     if (verified)
         return "付款已确认；不要再次展示付款动作，继续读取同一 Checkout。";
     if (terminal)
@@ -52,11 +60,7 @@ function payInstruction(options, verified, terminal, hasAction, hasQR, hasWallet
         return "Payment Intent 尚未返回可展示动作；不要猜测渠道链接，回到同一 Checkout 查询。";
     const platform = platformKeyForHost(options.host);
     if (isWorkBuddyPlainChat(options.agentType, platform)) {
-        if (hasQR && hasWallet)
-            return `这是受控逃生入口。读取 handoff.qr_image_url 的完整字符串，原样作为 files 数组唯一元素调用 present_files({ files: ["<完整 qr_image_url>"] })；右侧预览打开后说明金额 ${amount}、发送 handoff.mobile_wallet_url 并停止等待。如果 present_files 失败，发送 handoff.qr_image_url 和 handoff.mobile_wallet_url 并说明二维码预览未打开，然后停止。不要立即查询、创建替代 Checkout 或 Payment Intent。`;
-        if (hasQR)
-            return `这是受控逃生入口。读取 handoff.qr_image_url 的完整字符串，原样作为 files 数组唯一元素调用 present_files({ files: ["<完整 qr_image_url>"] })；右侧预览打开后说明金额 ${amount} 并停止等待。如果 present_files 失败，把 handoff.qr_image_url 作为可点击链接发送给用户并说明二维码预览未打开，然后停止。不要立即查询、创建替代 Checkout 或 Payment Intent。`;
-        return `这是受控逃生入口。说明金额 ${amount}，把 handoff.mobile_wallet_url 作为可点击链接发送给用户，然后停止等待；不要立即查询、创建替代 Checkout 或 Payment Intent。`;
+        return `这是受控逃生入口。说明金额 ${amount}，把 handoff.url 作为可点击链接发送给用户，然后停止等待。不要调用 present_files，不要立即查询、创建替代 Checkout 或 Payment Intent。`;
     }
     if (options.host === "codex" || options.host === "claude-code")
         return "这是受控逃生入口；把 handoff 中的二维码或钱包链接实际发到当前桌面对话，然后停止等待。";

package/dist/src/commands/refund.js

@@ -23,6 +23,18 @@ function refundStateEnvelope(refund, status) {
         instruction = "退款已成功；交付永久关闭。";
     if (refund.status === "cancelled" || refund.status === "rejected")
         instruction = "退款未执行，交付资格可恢复；旧 grant 不会复活，需要用户重新授权。";
+    if (refund.status === "failed") {
+        if (refund.failure_class === "known_no_effect")
+            instruction = "退款渠道请求确认未发送；不要自行重试。请用户联系平台管理员决定是否重新执行。";
+        else if (refund.failure_class === "retryable")
+            instruction = "退款渠道明确返回可重试失败；不要自行重试。请用户等待平台管理员处理。";
+        else if (refund.failure_class === "outcome_unknown")
+            instruction = "退款请求结果未知，交付继续锁定；必须先由平台对账，禁止重试或重复申请。";
+        else if (refund.failure_class === "permanent")
+            instruction = "退款渠道明确拒绝本次退款；不要重试。请用户联系平台支持。";
+        else
+            instruction = "退款执行失败；不要重试或重复申请，请用户联系平台支持。";
+    }
     return {
         status,
         result: {

package/dist/src/commands/services.js

@@ -3,6 +3,7 @@ import { validateContext } from "../state/client_context.js";
 import { dispatchRender } from "../render/index.js";
 import { ensureIdeImageAttach } from "../render/ide.js";
 import { buildCheckoutHandoff, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
+import { localizeCardURL, normalizeCardLocale } from "../render/locale.js";
 import { buildAgentChatHandoff } from "../render/markdown.js";
 import { platformKeyForHost } from "../render/plan.js";
 import { renderTerminalQR } from "../render/qr.js";
@@ -413,14 +414,18 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
     const checkout = response.checkout;
     const checkoutID = checkout.checkout.checkout_id;
     const displayToken = checkout.display_token;
+    const locale = normalizeCardLocale(options.locale);
     const checkoutURL = tokenizedCheckoutURL(checkout.checkout_url, displayToken, checkout.qr_payload);
+    const cardURL = localizeCardURL(absolutePublicURL(config.baseURL, checkout.card_url ?? fallbackCardURL(config.baseURL, checkoutID, displayToken)), locale);
+    const cardPNGURL = localizeCardURL(absolutePublicURL(config.baseURL, checkout.card_png_url ?? checkout.qr_png_url ?? fallbackCardPNGURL(config.baseURL, checkoutID, displayToken)), locale);
     const plan = buildCheckoutQRPlan({
         host,
         checkoutID,
         checkoutURL,
+        cardURL,
         displayToken,
         qrPayload: checkout.qr_payload,
-        ...(checkout.qr_png_url ? { qrPNGURL: absolutePublicURL(config.baseURL, checkout.qr_png_url) } : {}),
+        qrPNGURL: cardPNGURL,
         nextAction: checkout.checkout.next_action,
         orderItems: response.cart.items.map((item) => ({
             title: item.title,
@@ -430,6 +435,7 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
         })),
         orderCurrency: checkout.checkout.currency,
         ...(options.agentType ? { agentType: options.agentType } : {}),
+        locale,
     });
     options.persistHandoff?.({
         serviceExecutionID,
@@ -458,7 +464,7 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
             ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
         });
     }
-    const envelope = buildServicesCheckoutEnvelope(response, checkoutURL, plan, config.baseURL, options.agentType, options.target);
+    const envelope = buildServicesCheckoutEnvelope(response, checkoutURL, plan, options.agentType, options.target);
     const plainResult = [
         `service_execution_id: ${response.binding.service_execution_id}`,
         `checkout_id: ${checkoutID}`,
@@ -939,18 +945,18 @@ function parseValue(value) {
         return Number(value);
     return value;
 }
-function buildServicesCheckoutEnvelope(response, checkoutURL, plan, baseURL, agentType, target) {
+function buildServicesCheckoutEnvelope(response, checkoutURL, plan, agentType, target) {
     const checkout = response.checkout;
     const platform = platformKeyForHost(plan.host);
     const amount = formatMoney(checkout.checkout.amount_minor, checkout.checkout.currency);
     const presentationHandoff = buildCheckoutHandoff({
         platform,
-        url: checkoutURL,
+        url: plan.linkOnlyURL ?? checkoutURL,
         amount,
         plan,
         ...(agentType ? { agentType } : {}),
         ...(target ? { target } : {}),
-        ...(checkout.qr_png_url ? { qrImageURL: absolutePublicURL(baseURL, checkout.qr_png_url) } : {}),
+        ...(plan.preferredQRSources[0] ? { qrImageURL: plan.preferredQRSources[0] } : {}),
         ...(plan.ideImageAttach?.status === "downloaded" && plan.ideImageAttach.localPath
             ? { localPath: plan.ideImageAttach.localPath }
             : {}),
@@ -968,12 +974,19 @@ function buildServicesCheckoutEnvelope(response, checkoutURL, plan, baseURL, age
         handoff: presentationHandoff.handoff,
         instruction: presentationHandoff.instruction,
         next: {
-            command: `itpay checkout --id ${checkout.checkout.checkout_id} --token ${checkout.display_token} --json`,
+            command: plan.afterActionCommand ?? `itpay checkout --id ${checkout.checkout.checkout_id} --token ${checkout.display_token} --json`,
             reason: "仅在用户完成付款操作或要求查询后，读取同一 Checkout 的权威状态",
         },
         recovery: [],
     };
 }
+function fallbackCardURL(baseURL, checkoutID, displayToken) {
+    const root = baseURL.replace(/\/$/, "");
+    return `${root}/v1/checkouts/${encodeURIComponent(checkoutID)}/card?display_token=${encodeURIComponent(displayToken)}`;
+}
+function fallbackCardPNGURL(baseURL, checkoutID, displayToken) {
+    return `${fallbackCardURL(baseURL, checkoutID, displayToken)}.png`.replace("/card?", "/card.png?");
+}
 function checkoutCapabilityID(response, fallback = "") {
     return response.capability_id || fallback;
 }

package/dist/src/main.js

@@ -691,6 +691,7 @@ program
     .option("--require-contact <fields>", "comma-separated required contact fields: email,phone")
     .option("--qr-format <format>", "unicode|utf8|ansi|terminal")
     .option("--qr-file <path>", "explicit QR file path")
+    .option("--locale <locale>", "payment card language: zh-CN|en", "zh-CN")
     .option("--pay", "also create a payment intent and optionally wait for verification")
     .option("--method <alipay|wechatpay>", "payment method for --pay", "alipay")
     .option("--no-wait", "do not wait for payment verification after --pay")
@@ -752,6 +753,7 @@ program
             ...(requiredContactFields ? { requiredContactFields } : {}),
             ...(options.qrFormat ? { qrFormat: options.qrFormat } : {}),
             ...(options.qrFile ? { qrFilePath: options.qrFile } : {}),
+            locale: options.locale,
             ...(options.pay ? { pay: true, payMethod: options.method, noWait: options.wait === false, payTimeoutSec: timeout } : {}),
             ...(jsonOutput ? { jsonOutput: true } : {}),
         };
@@ -779,6 +781,7 @@ program
     .option("--target <target>")
     .option("--id <checkout_id>")
     .option("--token <display_token>")
+    .option("--locale <locale>", "payment card language: zh-CN|en", "zh-CN")
     .option("--json", "output compact JSON")
     .action(async (options) => {
     const config = loadConfig();
@@ -800,6 +803,7 @@ program
             ...(options.target ? { target: options.target } : {}),
             ...(config.agentType ? { agentType: config.agentType } : {}),
             baseURL: config.baseURL,
+            locale: options.locale,
             jsonOutput: Boolean(options.json),
         });
     }
@@ -1166,6 +1170,7 @@ services
     .option("--target <target>", "chat id / channel id / open id for IM hosts")
     .option("--qr-format <format>", "unicode|utf8|ansi|terminal")
     .option("--qr-file <path>", "explicit QR file path")
+    .option("--locale <locale>", "payment card language: zh-CN|en", "zh-CN")
     .option("--json", "output JSON instead of terminal text")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
@@ -1182,6 +1187,7 @@ services
             ...(options.target ? { target: options.target } : {}),
             ...(options.qrFormat ? { qrFormat: options.qrFormat } : {}),
             ...(options.qrFile ? { qrFilePath: options.qrFile } : {}),
+            locale: options.locale,
             jsonOutput: Boolean(options.json),
             persistHandoff: (handoff) => {
                 session.rememberCheckout({

package/dist/src/render/locale.js

@@ -0,0 +1,27 @@
+export function normalizeCardLocale(value) {
+    switch (value?.trim().toLowerCase()) {
+        case undefined:
+        case "":
+        case "zh":
+        case "zh-cn":
+        case "zh_cn":
+        case "cn":
+            return "zh-CN";
+        case "en":
+        case "en-us":
+        case "en_us":
+            return "en";
+        default:
+            throw new Error(`unsupported card locale: ${value}; expected zh-CN or en`);
+    }
+}
+export function localizeCardURL(value, locale) {
+    try {
+        const parsed = new URL(value);
+        parsed.searchParams.set("locale", locale);
+        return parsed.toString();
+    }
+    catch {
+        return value;
+    }
+}

package/dist/src/render/plain_chat.js

@@ -6,6 +6,10 @@
 import { ideImageAttachBlock } from "./ide.js";
 export function renderPlainChat(plan, options = {}) {
     const out = options.output ?? ((line) => process.stdout.write(line));
+    if (plan.linkOnlyURL) {
+        out(`${plan.summary}\nopen: ${plan.linkOnlyURL}\n`);
+        return;
+    }
     const brand = plan.preferredQRSources.find((src) => src.length > 0);
     const lines = [];
     lines.push(plan.summary);

package/dist/src/state/config.js

@@ -12,8 +12,8 @@ import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
 export const DEV_BASE_URL = "https://dev.itpay.ai";
-export const CLI_VERSION = "2.0.20";
-export const API_CONTRACT_REVISION = "sha256:ab3e76d7eee227c9192d41023c5bdf0e0e793bcad294287c75de6ac606f8caf7";
+export const CLI_VERSION = "2.0.22";
+export const API_CONTRACT_REVISION = "sha256:0c6470d9e3c1b4ec317d6c1b0b597acc13ec10d39312f994ece4cfd25cb0b65e";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";

package/docs/agent/buyer/payment-flow.json

@@ -31,7 +31,7 @@
     "Use only handoff fields returned for the current Host and make them actually visible to the human.",
     "Before creating a single-Service Checkout, send the exact price confirmation requested by the current instruction, stop, and wait for explicit human agreement.",
     "After presenting a Checkout, stop. Run the returned next.command only after the human completes the payment action or asks to query the same Checkout.",
-    "For workbuddy with plain-chat, present the returned HTTPS QR with present_files exactly as instructed; presentation failure falls back only to handoff.url and never creates another payment resource.",
+    "For workbuddy with plain-chat, send or open the fully rendered Card Link in handoff.url and never call present_files or create another payment resource.",
     "For openclaw with telegram, execute the returned native message action using the current trusted target. For any other explicit OpenClaw Host, show the returned HTTPS QR image and Checkout URL.",
     "Payment is verified only by Backend Checkout or Order state, never by QR rendering, redirect, or user claim.",
     "A terminal payment state must never display another payment handoff."

package/docs/agent/buyer/render-hosts.json

@@ -33,7 +33,7 @@
     {
       "agent_type": "workbuddy",
       "default_host": "plain-chat",
-      "responsibility": "when handoff.qr_image_url exists, use its exact HTTPS value as the only files element in present_files; otherwise send the Checkout URL without calling present_files; show the amount and stop"
+      "responsibility": "show the amount and send or open handoff.url, which is the fully rendered HTML Card Link; never call present_files; then stop"
     },
     {
       "agent_type": "kimi-code",
@@ -63,7 +63,7 @@
   "agent_rules": [
     "Agent Type is stable identity; Host is presentation and may be explicitly overridden.",
     "A local QR path is not visible until a desktop Agent attaches or renders that file on the human-facing surface; WorkBuddy never receives a local QR path.",
-    "For workbuddy with plain-chat, call present_files exactly as the returned instruction says. If it fails, send only handoff.url, report that the preview did not open, and stop.",
+    "For workbuddy with plain-chat, send or open only the rendered handoff.url and never call present_files, inspect files, or rebuild a QR.",
     "Do not claim the handoff was shown until both a usable payment image or QR and the Checkout URL are visible.",
     "IM Hosts that require a target must receive --target before Checkout creation. OpenClaw has no default Host; Kimi Code uses terminal.",
     "OpenClaw Telegram uses flat url/value buttons for deployed-version compatibility. A grant_confirmed callback carries only the Checkout ID, never a display token, and never proves payment or an active grant."
@@ -72,7 +72,7 @@
     "Do not expose display tokens separately from the tokenized Checkout handoff.",
     "Do not print base64 images, mirror lists, renderer debug state, or provider QR URLs.",
     "Do not claim a desktop attachment exists when only a filesystem path was printed.",
-    "Do not inspect, download, or regenerate a local QR file for WorkBuddy."
+    "Do not call present_files or inspect, download, or regenerate a local QR file for WorkBuddy."
   ],
   "next_docs": [
     {

package/docs/cli-reference/agent-types.md

@@ -14,7 +14,7 @@
 | `codex-cli` | `terminal` | 在用户可见终端渲染二维码并输出付款链接；若用户不看该终端，要求改用正确 Host。 |
 | `claude-code-desktop` | `claude-code` | 返回桌面对话可展示的 Markdown 图片和付款链接，要求先展示再等待。 |
 | `claude-code-cli` | `terminal` | 在用户可见终端输出二维码和链接，不声称已在桌面对话展示。 |
-| `workbuddy` | `plain-chat` | 只返回 HTTPS 二维码和付款链接；要求 Agent 用 `present_files` 在右侧预览打开二维码，不返回或检查本地图片路径。 |
+| `workbuddy` | `plain-chat` | 只返回完整渲染的 HTML Card Link；直接打开链接，不调用 `present_files`，不返回或检查本地图片路径。 |
 | `kimi-code` | `terminal` | 使用标准 CLI 引导，在用户可见终端渲染二维码和付款链接。 |
 | `openclaw` | 无；必须显式传入 | `--host telegram` 使用 OpenClaw 原生 `message` action；其他入口返回标准 HTTPS 二维码和付款链接。 |
 
@@ -43,9 +43,9 @@
     "amount": "<amount> <currency>"
   },
   "handoff": {
-    "url": "<checkout_url>",
+    "url": "<checkout_or_rendered_card_url>",
     "qr_local_path": "<desktop_optional_local_path>",
-    "qr_image_url": "<workbuddy_optional_absolute_https_png>",
+    "qr_image_url": "<non_workbuddy_optional_absolute_https_png>",
     "markdown": "<desktop_optional_host_ready_markdown>"
   },
   "instruction": "<agent-type-specific instruction>",
@@ -66,11 +66,11 @@
 | `claude-code-desktop / claude-code` | `url, qr_local_path, markdown` |
 | `codex-cli / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
 | `claude-code-cli / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
-| `workbuddy / plain-chat` | `url, qr_image_url` |
+| `workbuddy / plain-chat` | `url`（完整渲染的 HTML Card Link） |
 | `kimi-code / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
 | `openclaw / telegram` | `url, qr_image_url, agent_action` |
 | `openclaw / other` | `url, qr_image_url` |
 
-WorkBuddy instruction 只在 `handoff.qr_image_url` 存在时要求读取其完整字符串并作为 `files` 数组唯一元素调用 `present_files`。如果该可选字段不存在，必须直接发送 `handoff.url`，明确不要调用 `present_files`。两种情况都要停止等待；不能检查本地文件、下载或重建二维码、调用 `pay` 或创建替代付款资源。显式 `--host` 仍覆盖默认展示方式，因此只有 `workbuddy + plain-chat` 使用该规则。
+WorkBuddy instruction 必须直接发送并打开 `handoff.url`，明确禁止 `present_files`。这个 URL 指向 Backend 已渲染的 HTML Card；不能检查本地文件、下载或重建二维码、调用 `pay` 或创建替代付款资源。显式 `--host` 仍覆盖默认展示方式。
 
 OpenClaw Telegram 的 `handoff.agent_action` 是可原样执行的原生 `message` tool action。`presentation` 只包含标准 `blocks.buttons`：`📱 手机点这儿支付` 使用扁平 `url`，`📋 已授权给我读` 使用扁平 `value=itp:grant_confirmed:<checkout_id>`；二维码单独使用 action 的 `media`。CLI `instruction` 必须要求 Agent 原样执行该 action，不得改写 Presentation、换用其他消息工具或声称普通文本回复等同于已发送按钮。收到授权 callback 后立即执行 `next.command` 查询同一 Checkout，再只跟随后端返回的同一 Execution grant 流程；callback 只携带 Checkout ID，不携带 display token，也不证明付款或 grant 已生效。OpenClaw `target` 使用原生 chat target（如 `5559456744` 或 `-1001234567890:topic:42`），不添加 `telegram:` 前缀。

package/docs/cli-reference/commands/buy.md

@@ -165,7 +165,7 @@ itpay buy \
 | `codex-cli` | `terminal` | `url` | 非 JSON 模式在用户可见终端渲染二维码；始终保留付款链接。 |
 | `claude-code-desktop` | `claude-code` | `url`、可用时 `qr_local_path` 和 `markdown` | 把 Markdown handoff 发到当前桌面对话，不能只输出本地路径。 |
 | `claude-code-cli` | `terminal` | `url` | 在用户可见终端展示；不能声称桌面对话已收到图片。 |
-| `workbuddy` | `plain-chat` | `url, qr_image_url?` | 有 `qr_image_url` 时调用 `present_files`；没有时只发送金额和 `url` 且不调用工具。两者都停止，不读取本地文件。 |
+| `workbuddy` | `plain-chat` | `url` | `url` 是完整渲染的 HTML Card Link；直接发送/打开，不调用 `present_files`，然后停止。 |
 | `kimi-code` | `terminal` | `url` | 使用标准 CLI 非 JSON 终端二维码和链接。 |
 | `openclaw` | 必须显式 | Telegram 返回 `url,qr_image_url,agent_action`；其他入口返回 `url,qr_image_url` | Telegram 执行原生 `message` action；其他入口直接展示图片和链接。 |
 

package/docs/cli-reference/commands/checkout.md

@@ -71,7 +71,7 @@ token 缺失或不匹配时使用本机句柄恢复。只有请求的 Checkout
 | `codex-cli` | `url`；普通文本模式渲染终端二维码。 |
 | `claude-code-desktop` | `url, qr_local_path, markdown`；原样发送 Markdown。 |
 | `claude-code-cli` | `url`；普通文本模式渲染终端二维码。 |
-| `workbuddy` | `url, qr_image_url?`；有二维码 URL 时按 `services checkout` 相同规则调用 `present_files`，没有时只发送 Checkout URL，不生成本地文件。 |
+| `workbuddy` | 只返回 `url`；它是完整渲染的 HTML Card Link。直接打开，不调用 `present_files`，不生成本地文件。 |
 | `kimi-code` | `url`；普通文本模式渲染标准终端二维码。 |
 | `openclaw` | Telegram 为 `url,qr_image_url,agent_action`；instruction 强制原样执行 action。`📋 已授权给我读` callback 触发同一 Checkout 查询，再由 Backend 决定是否进入 grant 读取；其他显式 Host 为 `url,qr_image_url`。 |
 

package/docs/cli-reference/commands/install.md

@@ -117,7 +117,7 @@ OpenClaw 额外明确没有默认入口：
 | `codex-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
 | `claude-code-desktop` | `claude-code` | 桌面对话必须实际展示二维码和付款链接。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
-| `workbuddy` | `plain-chat` | 会持久化 `~/.itpay-v3` 的 Bash 调用先设 Shell 工具参数 `dangerouslyDisableSandbox=true`；拒绝权限时停止，不切换 Node、不删除 identity、不处理 lock。Checkout 返回 `qr_image_url` 时按 instruction 调用 `present_files`。 |
+| `workbuddy` | `plain-chat` | 会持久化 `~/.itpay-v3` 的 Bash 调用先设 Shell 工具参数 `dangerouslyDisableSandbox=true`；拒绝权限时停止。Checkout 只发送/打开渲染后的 Card Link，不调用 `present_files`。 |
 | `kimi-code` | `terminal` | 使用标准 CLI 流程和终端展示，不增加 Kimi 专属命令。 |
 | `openclaw` | 无 | 必须显式提供当前入口；Telegram 使用原生 action，其他入口展示标准二维码和链接。 |
 

package/docs/cli-reference/commands/pay.md

@@ -100,6 +100,6 @@ API 安全合同要求后端验证 display token 是该 Checkout 当前有效的
 | `codex-cli` | `terminal` | 只在用户可见终端展示渠道动作。 |
 | `claude-code-desktop` | `claude-code` | 把安全 handoff 发到当前桌面对话。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示渠道动作。 |
-| `workbuddy` | `plain-chat` | 有 `qr_image_url` 时调用 `present_files`；若同时有钱包链接则发送 `mobile_wallet_url`。二维码预览失败时只发送实际存在的二维码/钱包链接；只有钱包链接时直接发送它。展示后停止，不立即查询或创建替代付款。 |
+| `workbuddy` | `plain-chat` | 受控逃生入口只返回一个可点击的 `handoff.url`；不得调用 `present_files`。展示后停止，不立即查询或创建替代付款。 |
 
 Host 只改变 instruction；Payment Intent ID、金额、状态、重试语义和权限必须一致。

package/docs/cli-reference/commands/refund/get.md

@@ -49,7 +49,12 @@ itpay refund get <refund_request_id> [--json]
 
 - `succeeded`：instruction 明确“退款已成功；交付永久关闭”，`next=null`。
 - `cancelled/rejected`：说明交付资格可恢复，但旧 grant 不复活，需要用户重新授权，`next=null`。
-- `failed`：是否继续锁定以 `access_locked` 和 `failure_class` 的服务器裁定为准，`next=null`。
+- `failed + known_no_effect`：渠道请求确认未发送；Agent 不重试，由平台管理员决定是否重新执行，`next=null`。
+- `failed + retryable`：渠道明确返回可重试失败；Agent 不重试，等待平台管理员处理，`next=null`。
+- `failed + outcome_unknown`：渠道可能已受理；交付继续锁定，必须先对账，禁止重试或重复申请，`next=null`。
+- `failed + permanent`：渠道明确拒绝；停止并联系平台支持，`next=null`。
+
+`decision_mode=manual` 只说明该退款采用人工裁定，不得覆盖上述失败终态的 instruction。CLI 永远不向 Agent 暴露 Provider 原始响应、签名、URL、支付标识或内部错误文本。
 
 CLI 不因为退款终态自行修改订单或 grant。
 

package/docs/cli-reference/commands/refund/watch.md

@@ -44,7 +44,7 @@ itpay refund watch <refund_request_id> [--interval <seconds>] [--timeout <second
 }
 ```
 
-其他终态使用与 `refund get` 相同的锁、恢复资格和旧 grant 规则。
+其他终态使用与 `refund get` 相同的锁、恢复资格和旧 grant 规则。特别是 `failed` 必须按 `failure_class` 区分 `known_no_effect`、`retryable`、`outcome_unknown` 和 `permanent`；任何一种都不向 Agent 返回重试命令。
 
 ## Timeout 输出
 

package/docs/cli-reference/commands/services/checkout.md

@@ -81,16 +81,16 @@ itpay services checkout <service_execution_id> --resume
 | `codex-cli` | `handoff={url}`；普通文本模式在用户可见终端渲染二维码。 |
 | `claude-code-desktop` | `handoff={url,qr_local_path,markdown}`；把 `handoff.markdown` 原样发送到当前桌面对话。 |
 | `claude-code-cli` | `handoff={url}`；普通文本模式在用户可见终端渲染二维码。 |
-| `workbuddy` | `handoff={url,qr_image_url?}`；有 `qr_image_url` 时读取完整值并作为 `files` 数组唯一元素调用 `present_files`；没有时直接发送金额与 `url`，不得调用 `present_files`。两者随后都停止，不得检查或生成本地文件。 |
+| `workbuddy` | `handoff={url}`；`url` 是完整渲染的 HTML Card Link。直接发送/打开并停止，不得调用 `present_files`、检查或生成本地文件。 |
 | `kimi-code` | `handoff={url}`；复用标准 CLI 终端展示。 |
 | `openclaw` | 必须显式传 Host；Telegram 还必须传 OpenClaw 原生 Target，并返回必须原样执行的 `message` action；其他入口返回标准 `url,qr_image_url`。 |
 
 WorkBuddy 的准确 instruction 语义必须完整包含：
 
 ```text
-Backend 尚未确认付款。读取 handoff.qr_image_url 的完整字符串，原样作为 files 数组唯一元素调用 present_files({ files: ["<完整 qr_image_url>"] })；确认右侧二维码预览已打开后，向用户说明金额并发送 handoff.url，然后停止等待。如果 present_files 失败，只发送 handoff.url 并说明二维码预览未打开，然后停止。不要检查本地文件，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。
+Backend 尚未确认付款。向用户说明金额，直接发送并打开 handoff.url，然后停止等待。不要调用 present_files，不要检查本地文件，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。
 ```
 
-若 `qr_image_url` 缺失，准确 instruction 必须改为：说明本次没有可展示二维码，发送金额与 `handoff.url`，明确不要调用 `present_files`，然后遵守相同停止和付款证明规则。
+`--locale` 默认 `zh-CN`，可显式使用 `--locale en`。语言只影响 Card 渲染，不改变 Checkout、付款或恢复状态。
 
 OpenClaw 的 Host/Target 校验必须发生在读取 execution 后、创建 Checkout 前；校验失败不能调用 Checkout 创建接口。Telegram `agent_action.arguments.presentation` 只使用 `blocks.buttons`，其中 `📱 手机点这儿支付` 使用扁平 `url`，`📋 已授权给我读` 使用 `value=itp:grant_confirmed:<checkout_id>`。准确 instruction 必须要求 Agent 立即用原生 `message` tool 原样执行 `handoff.agent_action`，不得改写 Presentation、换工具或用普通回复冒充按钮已发送。收到该 callback 表示用户声明已在收银台授权读取；Agent 立即执行 `next.command` 查询同一 Checkout，再只按 Backend 返回的 `next.command` 进入同一 Execution grant 流程。callback 不包含 display token，也不证明付款或 grant active；Backend 未返回 `grant_active` 前不得读取结果。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "The single ItPay CLI entry point for buy workflows and future sell workflows.",
   "type": "module",
   "bin": {

package/skills/itpay/SKILL.md

@@ -85,8 +85,8 @@ When `status` is `human_checkout_required`, make the amount, ItPay Checkout QR,
 
 - Desktop Agents: send `handoff.markdown` unchanged; confirm QR, amount, and link are visible, then stop.
 - CLI Agents: show the terminal QR, amount, and link in the watched terminal, then stop; never claim a desktop image was shown.
-- WorkBuddy with `plain-chat`: when `handoff.qr_image_url` exists, use its complete value as the only `files` element in `present_files`; confirm the right-side QR preview opened, show amount and `handoff.url`, then stop. If it is absent, send amount and `handoff.url`, do not call `present_files`, then stop.
-- If WorkBuddy `present_files` fails, send only `handoff.url`, report the failure, and stop. Never inspect files, switch Node, rebuild a QR, call `pay`, or create another Checkout.
+- WorkBuddy with `plain-chat`: `handoff.url` is the fully rendered ItPay Card Link. Show the amount, send/open that link, then stop. Never call `present_files`, inspect files, download or rebuild a QR, call `pay`, or create another Checkout.
+- Desktop image hosts receive the PNG rendered from that same Card HTML. `--locale` defaults to `zh-CN`; use `--locale en` only when the human needs English.
 - An explicit `--host` overrides presentation only. It never changes Agent identity or payment state.
 
 Run `next.command` only after the human says they acted or asks for status. QR rendering, redirects, and human claims are not payment proof; only Backend Checkout or Order state is. Normal payment uses the Checkout page; `pay` and `buy --pay` are operator escape hatches, never recovery.