概述
自定义 UI 是可选的。如果插件的使用场景要求用户查看、比较、编辑、确认或浏览结构化信息,可以添加 UI。请确保 MCP 工具在没有组件时仍然可用,这样 ChatGPT 和 Codex 无需 UI 也能完成工作流。
MCP 服务器为指定的工具返回 UI 资源。组件在 ChatGPT 的 iframe 中运行,通过 MCP Apps 桥接接口与主机通信(通过 postMessage 传输 JSON-RPC 消息),并随对话一起显示。开放的 MCP Apps 标准使同一套 UI 可以在不同的兼容主机上运行。
从 MCP Apps 入手
ChatGPT 实现了开放的 MCP Apps 标准,用于呈现 MCP 服务器返回的 UI。MCP Apps 定义了服务器如何将工具与 UI 资源关联,以及 iframe 如何与主机通信。
开发新的 UI 时:
- 使用
_meta.ui.resourceUri声明 UI 资源。 - 使用
ui/*JSON-RPC 桥接接口,通过postMessage处理初始化、通知、工具调用、消息和模型可见的上下文。 - 确保工具在没有 UI 时仍然可用,以便模型在不渲染组件的客户端中也能完成工作流。
以这套标准为基础,同一套 UI 就能在 ChatGPT 和其他兼容 MCP Apps 的主机上运行。
实现时,请参阅 MCP Apps 规范。
有关侧边栏应用、文件查看器和功能更丰富的表单,请参阅扩展程序。
添加 ChatGPT 扩展功能
在 MCP Apps 工作流正常运行后,仅对共享规范未涵盖的功能使用 window.openai。这些可选扩展功能可以改善 ChatGPT 中的使用体验,同时保持基础 UI 的可移植性。
优先使用共享字段和方法
只要共享规范涵盖所需功能,就使用相应的 MCP Apps 字段或方法:
| 目标 | MCP Apps 标准 | ChatGPT 兼容别名 |
|---|---|---|
| 将工具与 UI 资源关联 | _meta.ui.resourceUri |
_meta["openai/outputTemplate"] |
| 接收工具输入 | ui/initialize + ui/notifications/tool-input |
window.openai.toolInput |
| 接收工具结果 | ui/notifications/tool-result |
window.openai.toolOutput |
| 从 UI 调用工具 | tools/call |
window.openai.callTool |
| 发送后续消息 | ui/message |
window.openai.sendFollowUpMessage |
现有集成仍可使用这些兼容别名。新的 UI 应使用中间一列中的共享字段和桥接方法。
扩展功能示例包括:
- 使用
window.openai.requestCheckout实现即时结账。 - 使用
window.openai.uploadFile、window.openai.selectFiles和window.openai.getFileDownloadUrl在 ChatGPT 中处理文件。 - 使用
window.openai.requestModal打开由主机控制的模态窗口。 - 使用
window.openai.widgetState和window.openai.setWidgetState持久化小组件状态。
逐项检测主机是否支持所需的扩展功能,并在可行时提供回退方案:
const openai = typeof window !== "undefined" ? window.openai : undefined;
if (openai?.requestModal) {
await openai.requestModal({
template: "ui://widget/details.html",
});
} else {
document.body.textContent = "This host does not support modals.";
}避免根据主机或产品名称选择执行分支。请检测 UI 所需的具体功能是否可用。
有关扩展接口的签名和示例,请参阅 window.openai 组件桥接接口参考。
可选的 OpenAI 组件库
@openai/apps-sdk-ui 组件库提供与 ChatGPT 容器风格一致的现成按钮、卡片、输入控件和基础布局组件。如果您希望保持样式统一,又无需重新实现基础组件,可以使用这个库。
您还可以浏览 GitHub 上的 UI 示例代码仓库。
选择呈现方式
先使用内嵌 UI,仅在工作流需要时申请更大的显示空间。选择占用空间最小、又能让用户理解结果或完成任务的呈现方式。
内嵌卡片
使用内嵌卡片展示单项结果、请用户确认或提供少量操作。卡片应可独立使用,避免多层导航。

内嵌轮播
如果用户需要快速浏览少量同类选项并从中选择,且这些选项主要靠图片等视觉内容展示,可以使用内嵌轮播。

全屏
对于需要较大空间的复杂任务,例如查看地图、在画布上编辑或浏览详细信息,请使用全屏模式。ChatGPT 的消息输入框在全屏模式下仍然可用,设计 UI 时应考虑用户如何配合使用输入框。

画中画
如果对话继续进行时,用户仍需看到正在进行的活动,例如实时会话、游戏或视频,请使用画中画。

有关布局、交互、视觉设计和无障碍设计的详细指导,请参阅 UI 指南。
将数据处理与 UI 渲染分开
解耦模式
如果每次调用工具都附带小组件模板,ChatGPT 可能会过于频繁地重新渲染 iframe。建议将处理数据的工具与渲染工具分开:
- 数据工具获取、计算或修改数据,仅返回工具结果。
- 渲染工具接收最终数据并返回小组件模板。
这样,模型可以先分析获取的数据,再决定是否向用户呈现 UI,从而更有可能实现用户明确提出的具体目标。
这种模式是 MCP Apps 架构的一部分。
在实践中,许多 UI 集成采用以下分工:
- 搜索或获取工具(先获取数据): 返回 ID 及其元数据,不附带小组件模板。
- 渲染工具(例如
render_listings_widget): 接收准备好的 ID 列表并渲染小组件。
只有渲染工具才应包含 _meta.ui.resourceUri。
解耦后的调用流程
推荐的调用流程如下:
- 模型调用数据工具(例如
roll_dice)。 - 模型接收数据工具返回的
structuredContent。 - 模型使用这些数据调用渲染工具。
- 小组件根据模型检查过的最终上下文渲染一次。
示例:针对房源的追问
假设您的插件显示房源卡片和地图,但服务器端的 search 工具只支持按城市、价格、卧室数和卫生间数等基本条件筛选,无法按学区筛选。
如果用户问“这些房源中,哪些位于里士满小学的学区内?”,可以利用解耦模式来处理:
search先按较宽泛的条件搜索,返回候选房源的 ID 和元数据。- 模型根据用户的追问进一步筛选候选房源。
- 模型调用
render_listings_widget,只传入筛选后保留的 ID。 - 小组件展示最终筛选出的房源。
最佳实践:
- 让数据工具可以复用。返回完整的
structuredContent,供后续工具调用使用。 - 让渲染工具专注于呈现。不要在渲染处理函数中混入业务逻辑。
- 在渲染工具的描述中说明调用依赖关系(例如“务必先调用
roll_dice”)。 - 仅在确有需要时重新运行工具。对于“重新掷骰子”等局部交互,让 UI 直接调用数据工具,无需重新挂载小组件。
解耦示例
如果使用 Go,请使用 github.com/modelcontextprotocol/go-sdk/mcp 的 v1.8.0 版本。安装浏览器端依赖项时,一并安装 esbuild 和 @modelcontextprotocol/ext-apps。运行 npm exec -- esbuild dice-widget.ts --bundle --format=esm --outfile=dice-widget.js 打包下文的浏览器端组件,然后在同一目录中运行 Go 服务器。
如果使用 Ruby 服务器,请安装 mcp gem,版本为 1.10.0。按下文说明构建浏览器端组件,然后从项目目录运行服务器。
以下示例将掷骰子和渲染结果拆分为两个工具:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod/v3";
import { build } from "esbuild";
import { fileURLToPath } from "node:url";
const TEMPLATE_URI = "ui://widget/dice.html";
const server = new McpServer(
{ name: "Decoupled dice", version: "1.0.0" },
{ capabilities: { tools: {} } }
);
// Bundle the same browser source that is type-checked and tested directly.
const widgetBundle = await build({
entryPoints: [fileURLToPath(new URL("./dice-widget.ts", import.meta.url))],
bundle: true,
format: "esm",
platform: "browser",
write: false,
});
const widgetScript = widgetBundle.outputFiles[0].text.replace(
/<\/script/gi,
"<\\/script"
);
const widgetHtml = `<!doctype html><html lang="en"><meta charset="utf-8"><title>Dice widget</title><body><script type="module">${widgetScript}</script></body></html>`;
server.registerResource("dice-widget", TEMPLATE_URI, {}, async () => ({
contents: [
{
uri: TEMPLATE_URI,
mimeType: "text/html;profile=mcp-app",
text: widgetHtml,
_meta: { ui: { prefersBorder: true } },
},
],
}));
// 1) Data tool: no output template, returns chainable structuredContent.
server.registerTool(
"roll_dice",
{
title: "Roll dice",
description: "Roll an N-sided die and return { sides, value }.",
inputSchema: { sides: z.number().int().min(2) },
outputSchema: {
sides: z.number().int().min(2),
value: z.number().int().min(1),
},
_meta: {
"openai/toolInvocation/invoking": "Rolling…",
"openai/toolInvocation/invoked": "Rolled.",
},
},
async ({ sides }) => {
const value = 1 + Math.floor(Math.random() * sides);
return {
structuredContent: { sides, value },
content: [{ type: "text", text: `Rolled ${value} on ${sides} sides.` }],
};
}
);
// 2) Render tool: owns the template and requires data from roll_dice.
server.registerTool(
"render_dice_widget",
{
title: "Render dice widget",
description:
"Render the dice widget from roll data. First call roll_dice, then pass its sides and value to this tool.",
inputSchema: {
sides: z.number().int().min(2),
value: z.number().int().min(1),
},
outputSchema: {
sides: z.number().int().min(2),
value: z.number().int().min(1),
},
_meta: {
ui: { resourceUri: TEMPLATE_URI },
"openai/toolInvocation/invoking": "Rendering…",
"openai/toolInvocation/invoked": "Rendered.",
},
},
async ({ sides, value }) => ({
structuredContent: { sides, value },
content: [
{
type: "text",
text: `Showing a ${sides}-sided roll: ${value}.`,
},
],
})
);
export default server;安装服务器依赖项时一并安装 esbuild,然后将以下浏览器端代码保存为 dice-widget.ts,放在与服务器文件相同的目录中:
import { App } from "@modelcontextprotocol/ext-apps";
const container = document.createElement("div");
container.style.cssText = "font-family: system-ui; padding: 8px;";
const resultLine = document.createElement("div");
resultLine.style.cssText = "font-size: 20px; margin-bottom: 6px;";
const output = document.createElement("span");
output.id = "out";
output.textContent = "—";
resultLine.append("Result: ", output);
const rerollButton = document.createElement("button");
rerollButton.id = "reroll";
rerollButton.textContent = "Re-roll";
rerollButton.disabled = true;
container.append(resultLine, rerollButton);
document.body.append(container);
const app = new App({ name: "Dice widget", version: "1.0.0" });
let latestInput: Record<string, unknown> = {};
let latestOutput: Record<string, unknown> = {};
function render(result: Record<string, unknown>) {
latestOutput = result;
output.textContent = String(result.value ?? "—");
}
app.ontoolinput = ({ arguments: input }) => {
latestInput = input ?? {};
};
app.ontoolresult = (result) => {
render(result.structuredContent ?? {});
};
// Call the data tool without remounting the widget.
rerollButton.onclick = async () => {
const candidate = latestOutput.sides ?? latestInput.sides;
const sides =
typeof candidate === "number" &&
Number.isInteger(candidate) &&
candidate >= 2
? candidate
: 6;
const next = await app.callServerTool({
name: "roll_dice",
arguments: { sides },
});
if (next.structuredContent) render(next.structuredContent);
};
await app.connect();
rerollButton.disabled = false;如果使用 Ruby,请将 dice-widget.ts 打包为 dice-widget.js,命令为 npm exec -- esbuild dice-widget.ts --bundle --format=esm --outfile=dice-widget.js。安装浏览器端依赖项时,一并安装 esbuild 和 @modelcontextprotocol/ext-apps。Ruby 服务器会读取编译后的文件。
管理状态
MCP 服务器提供的 UI 涉及三类状态:
| 状态类型 | 归属 | 生命周期 | 示例 |
|---|---|---|---|
| 业务数据(权威数据) | MCP 服务器或外部服务 | 长期有效 | 任务、工单、文档 |
| UI 状态(临时) | UI 实例 | UI 实例处于活动状态期间 | 选中的行、展开的面板、排序方式 |
| 跨会话状态(持久) | 您控制的存储系统 | 跨会话、跨对话 | 已保存的筛选条件、视图模式、工作空间 |
每个值都应保存在负责管理它的系统中。UI 应根据工具结果中的权威数据进行渲染,并在此基础上应用临时的呈现状态。
MCP 服务器或外部服务
│
├── 权威业务数据
│
▼
UI
│
├── 临时呈现状态
│
└── 渲染后的视图 = 业务数据 + UI 状态
将业务数据保存在服务器上
以业务数据为准。不要只将它保存在 UI 中。用户执行操作时:
- UI 调用 MCP 工具。
- 服务器验证请求并更新数据。
- 服务器返回更新后的权威数据快照。
- UI 渲染快照,同时保留与新快照兼容的呈现状态。
返回足够的结构化内容,让模型和 UI 都能理解新状态。这样,即使 UI 无法加载,用户仍能通过对话继续操作。
将临时 UI 状态保存在 UI 中
对于只影响呈现效果的值,例如选中的项目、打开的面板或尚未应用的筛选条件,请使用框架自身的状态管理机制。每个渲染出的 UI 实例都有独立的状态。
如果模型需要了解用户选中了什么或暂存了哪些编辑,请通过 ui/update-model-context 发送这些信息。这是 MCP Apps 用于更新模型可见上下文的机制,可在不同的兼容主机上使用。
ChatGPT 还提供可选的持久化机制,作用范围为单个小组件:
- 从
window.openai.widgetState读取当前快照。 - 使用
window.openai.setWidgetState(state)写入新快照。
setWidgetState 是同步方法。每次 UI 状态发生实质性变化后都应调用它,无需使用 await。
import { useState } from "react";
export function TaskList({
tasks,
}: {
tasks: { id: string; title: string }[];
}) {
const [state, setState] = useState(
window.openai?.widgetState ?? { selectedId: null }
);
function selectTask(selectedId: string) {
const nextState = { ...state, selectedId };
setState(nextState);
window.openai?.setWidgetState?.(nextState);
}
return (
<ul>
{tasks.map((task) => (
<li key={task.id}>
<button
type="button"
aria-pressed={state.selectedId === task.id}
onClick={() => selectTask(task.id)}
>
{task.title}
</button>
</li>
))}
</ul>
);
}小组件状态属于单个已渲染的 UI 实例。不要将其用作业务数据的权威来源或长期存储。
让模型能够看到图片
对于处理图片的 UI,请使用以下结构保存小组件状态:
modelContent:模型应看到的文本或 JSON。privateContent:仅供 UI 使用、模型不应看到的状态。imageIds:模型应在后续对话轮次中接收的文件 ID。
const selectedFiles = await window.openai.selectFiles();
window.openai.setWidgetState({
modelContent: "Review the currently selected images.",
privateContent: {
currentView: "image-viewer",
filters: ["crop", "sharpen"],
},
imageIds: selectedFiles.map((file) => file.fileId),
});只包含来自以下途径的文件 ID:使用 window.openai.uploadFile 上传文件、使用 window.openai.selectFiles 选择文件、通过工具输入的文件参数接收文件,或通过工具结果中的文件引用返回文件。
将跨会话状态保存在您的服务器上
对于需要跨对话、设备或会话保留的偏好设置和数据,请将其保存在您控制的存储系统中。验证用户身份,以便 MCP 服务器将每个请求关联到正确的账户。
添加持久化存储时:
- 将延迟控制在适合 UI 交互的范围内。
- 通过服务器端授权保护私有数据。
- 提前考虑数据驻留和合规要求。
- 对重试或多个 UI 实例并发产生的流量实施速率限制。
- 为存储的对象设置版本,以便迁移数据时不影响现有对话。
避免使用 localStorage 保存核心状态。UI 在隔离的 iframe 中运行,浏览器存储无法提供可靠的跨设备或跨会话数据层。
搭建组件项目
了解 MCP Apps 桥接接口和可选的 ChatGPT 扩展功能后,您就可以搭建组件项目了。
建议将组件代码与服务器逻辑分开。常见的项目结构如下:
plugin-ui/
server/ # MCP 服务器(Python 或 Node)
web/ # 用于打包组件的源文件
package.json
tsconfig.json
src/component.tsx
dist/component.js # 构建产物
创建项目并安装依赖项(建议使用 Node 18 或更高版本):
cd plugin-ui/web
npm init -y
npm install react@^19 react-dom@^19
npm install -D typescript esbuild
如果组件需要拖放、图表或其他功能库,请在此时添加。仅保留必要的依赖项,以减小打包体积。
编写 React 组件
入口文件应将组件挂载到 root 元素,并根据 MCP Apps 桥接接口传来的最新工具结果(例如通过 ui/notifications/tool-result 收到的结果)进行渲染。
示例页面展示了多种 UI,例如 Pizzaz 披萨餐厅列表。
浏览 Pizzaz 组件示例集
UI 示例中提供了以下组件,可供您设计自己的 UI 时参考:
- Pizzaz 列表: 按排名展示卡片,提供收藏按钮和引导用户执行操作的按钮。

- Pizzaz 轮播: 使用 Embla 实现横向滚动,展示如何布局大量媒体内容。

- Pizzaz 地图: 集成 Mapbox,支持全屏查看详情并与主机同步状态。

- Pizzaz 相册: 使用层叠式图库视图,方便用户详细了解某个地点。

- Pizzaz 视频: 通过脚本控制播放器,支持叠加显示内容和全屏控制。
每个示例都展示了如何打包资源、接入主机 API,以及如何组织状态以支持实际对话。复制最接近您使用场景的示例,然后调整数据层,使其适配您的工具响应。
React 辅助 Hook
以下辅助函数用于订阅 ui/notifications/tool-result:
import { useEffect, useState } from "react";
type ToolResult = { structuredContent?: unknown } | null;
export function useToolResult() {
const [toolResult, setToolResult] = useState<ToolResult>(null);
useEffect(() => {
const onMessage = (event: MessageEvent) => {
if (event.source !== window.parent) return;
const message = event.data;
if (!message || message.jsonrpc !== "2.0") return;
if (message.method !== "ui/notifications/tool-result") return;
setToolResult(message.params ?? null);
};
window.addEventListener("message", onMessage, { passive: true });
return () => window.removeEventListener("message", onMessage);
}, []);
return toolResult;
}根据 toolResult?.structuredContent 渲染 UI,并将其视为不受信任的输入。
小组件本地化
主机会将其区域设置同步到 document.documentElement.lang。使用该区域设置加载译文,并设置日期和数字的格式。使用以下示例前,请先运行 npm install react-intl,运行目录为 web/:
import { IntlProvider, FormattedMessage } from "react-intl";
const messages: Record<string, Record<string, string>> = {
"en-US": { greeting: "Hello" },
"es-ES": { greeting: "Hola" },
};
export function PluginUI() {
const locale = document.documentElement.lang || "en-US";
return (
<IntlProvider
locale={locale}
messages={messages[locale] ?? messages["en-US"]}
>
<FormattedMessage id="greeting" defaultMessage="Hello" />
</IntlProvider>
);
}为 iframe 打包组件
编写好 React 组件后,可以将其构建为单个 JavaScript 模块,以便服务器将其内嵌到页面中:
// package.json
{
"scripts": {
"build": "esbuild src/component.tsx --bundle --format=esm --jsx=automatic --outfile=dist/component.js"
}
}
运行 npm run build 生成 dist/component.js。如果 esbuild 报告缺少依赖项,请确认您运行 npm install 时位于 web/ 目录,且导入的名称与已安装的软件包名称一致(例如,注意区分 @react-dnd/html5-server-side 和 react-dnd-html5-server-side)。
将组件嵌入服务器响应
使用 MCP Apps UI 的 MIME 类型(text/html;profile=mcp-app)将组件公开为 MCP 资源。如果您使用 @modelcontextprotocol/ext-apps/server,请优先使用 RESOURCE_MIME_TYPE,避免直接写入该字符串:
import {
registerAppResource,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
import { readFileSync } from "node:fs";
const component = readFileSync("web/dist/component.js", "utf8");
registerAppResource(
server,
"project-board",
"ui://project-board/v1.html",
{},
async () => ({
contents: [
{
uri: "ui://project-board/v1.html",
mimeType: RESOURCE_MIME_TYPE,
text: `<div id="root"></div><script type="module">${component}</script>`,
_meta: {
ui: {
prefersBorder: true,
domain: "https://example.com",
csp: {
connectDomains: ["https://api.example.com"],
resourceDomains: ["https://static.example.com"],
},
},
},
},
],
})
);如果使用 Go,请使用 github.com/modelcontextprotocol/go-sdk/mcp 的 v1.8.0 版本。按前面的步骤构建 web/dist/component.js 后,从项目根目录运行 Go 服务器。
如果使用 Ruby,请安装 mcp gem,版本为 1.10.0。按前面的步骤构建 web/dist/component.js 后,从项目根目录运行服务器。
仅将资源 URI 与应渲染该组件的工具关联。为兼容更多 MCP Apps 主机,请使用 _meta.ui.resourceUri。ChatGPT 也支持兼容别名 _meta["openai/outputTemplate"]。
将资源 URI 视为缓存键。如果您对 HTML、JavaScript 或 CSS 做了不向后兼容的更改,请发布新的 URI,并更新所有引用该 URI 的工具。
内容安全策略(CSP)
准确声明组件要连接的域名,以及要从哪些域名加载资源:
connectDomains用于 API 请求。resourceDomains用于脚本、样式、图片及其他资源。frameDomains仅在组件必须嵌入来自特定源的 iframe 时使用。
默认禁止嵌套框架。请尽可能缩小每份允许列表的范围。插件审核时会检查声明的策略是否与 UI 的实际行为一致。
带有 UI 的插件可以嵌入与其 MCP 服务器同属一个可注册域名的页面,包括完整的现有编辑器和管理界面。例如,位于 https://api.example.com/mcp 的服务器可以嵌入 https://app.example.com,因为两者的可注册域名都是 example.com。在共享托管服务上,不同租户视为不同的域。使用同一家托管服务商并不能证明域名所有权。
在资源的 CSP 中,使用 _meta.ui.csp.frameDomains(或旧版字段 _meta["openai/widgetCSP"].frame_domains)逐一声明需要嵌入的 iframe 源。对于第三方域名,只有在嵌入页面所提供的功能对插件不可或缺时,才应通过 iframe 嵌入该页面。
提交使用 iframe 的插件时,您仍须说明理由。请逐一说明每个嵌入页面的用途、插件嵌入该页面的原因,以及由谁控制其域名。使用 iframe 可能需要额外审核或提交上一级审核。如果无法评估嵌入的内容,审批可能耗时更长,插件也可能被拒。即使嵌入页面与 MCP 服务器使用同一域名,也不能保证通过审核。
嵌入的页面仍须符合其他所有插件要求,包括结账和隐私方面的要求。
生产环境建议使用组件 UI 模板。
开发过程中,每次修改 React 代码后,您都可以重新构建组件包并热重载服务器。
在 UI 中提供结账功能
如果您希望用户通过插件的 UI 流程结账,请在用户确认前,使用组件展示商品、价格、条款和付款选项。确保底层商品目录工具和订单工具在没有 UI 时仍然可用,然后选择外部结账流程,或在条件允许时选择嵌入式支付方式。
默认使用外部结账
外部结账是推荐的方式,已普遍开放。请从组件链接到商家托管在您自己域名上的结账流程,并在那里处理以下事项:
- 定价和收款。
- 税费、折扣和手续费。
- 配送和订单履约。
- 退款、客户支持和合规事宜。
目前,只有用于购买实体商品的插件可获批准。除非 OpenAI 已为您的插件明确启用其他交易类别,否则请勿提供这些类别的交易。
使用已保存的付款方式
对于符合条件的实体商品交易,您可以提供可选 UI,让客户选择之前在您的服务中保存的付款方式。此流程可以显示符合条件的已保存付款方式,但不能收集新的付款凭据。您的 MCP 服务器负责处理交易,并返回权威的订单结果。
使用 ChatGPT 支付面板
通过 ChatGPT 支付面板进行嵌入式结账的功能目前处于封闭测试阶段,仅对部分交易市场开放,尚未向所有开发者或用户提供。
对于已启用此功能的集成,调用 window.openai.requestCheckout 即可打开 ChatGPT 支付面板:
const order = await window.openai.requestCheckout(checkoutSession);结账流程分为四步:
- MCP 工具在
structuredContent中返回结账会话。 - 组件显示订单明细、总额、条款和履约选项。
- 用户选择付款后,组件调用
requestCheckout(checkoutSession)。 - ChatGPT 将所选的支付令牌发送给 MCP 服务器的
complete_checkout工具。该工具通过相应的付款方式扣款,并返回已完成的订单。
结账会话必须包含:
- 唯一的会话 ID。
- 订单明细及各项数量。
- 以货币最小单位表示的整数总额。
- 支付服务商和商家的元数据。
- 必需的法律、隐私、退款和客户支持链接。
价格和订单状态以服务器数据为准。请验证支付令牌,确保操作具有幂等性,持久化保存订单,并返回以服务器数据为准的收据。切勿信任仅由组件计算的总额。
使用 payment_mode: "test" 测试端到端流程,无需实际划转资金。在组件中处理取消付款、付款被拒和支付服务商报错的情况。
有关结账会话的完整字段、支付服务商的行为、complete_checkout 的结果结构以及委托支付的要求,请参阅结账 API 参考。