如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
概览 智能体访问 ChatGPT 与 Codex 用户文档 使用场景

为 MCP 服务器添加 UI

让指定的 MCP 工具按需返回 UI 资源。

概述

自定义 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 时:

  1. 使用 _meta.ui.resourceUri 声明 UI 资源。
  2. 使用 ui/* JSON-RPC 桥接接口,通过 postMessage 处理初始化、通知、工具调用、消息和模型可见的上下文。
  3. 确保工具在没有 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 示例

有关布局、交互、视觉设计和无障碍设计的详细指导,请参阅 UI 指南。

将数据处理与 UI 渲染分开

解耦模式

如果每次调用工具都附带小组件模板,ChatGPT 可能会过于频繁地重新渲染 iframe。建议将处理数据的工具与渲染工具分开:

  • 数据工具获取、计算或修改数据,仅返回工具结果。
  • 渲染工具接收最终数据并返回小组件模板。

这样,模型可以先分析获取的数据,再决定是否向用户呈现 UI,从而更有可能实现用户明确提出的具体目标。

这种模式是 MCP Apps 架构的一部分。

在实践中,许多 UI 集成采用以下分工:

  • 搜索或获取工具(先获取数据): 返回 ID 及其元数据,不附带小组件模板。
  • 渲染工具(例如 render_listings_widget): 接收准备好的 ID 列表并渲染小组件。

只有渲染工具才应包含 _meta.ui.resourceUri。

解耦后的调用流程

推荐的调用流程如下:

  1. 模型调用数据工具(例如 roll_dice)。
  2. 模型接收数据工具返回的 structuredContent。
  3. 模型使用这些数据调用渲染工具。
  4. 小组件根据模型检查过的最终上下文渲染一次。

示例:针对房源的追问

假设您的插件显示房源卡片和地图,但服务器端的 search 工具只支持按城市、价格、卧室数和卫生间数等基本条件筛选,无法按学区筛选。

如果用户问“这些房源中,哪些位于里士满小学的学区内?”,可以利用解耦模式来处理:

  1. search 先按较宽泛的条件搜索,返回候选房源的 ID 和元数据。
  2. 模型根据用户的追问进一步筛选候选房源。
  3. 模型调用 render_listings_widget,只传入筛选后保留的 ID。
  4. 小组件展示最终筛选出的房源。

最佳实践:

  • 让数据工具可以复用。返回完整的 structuredContent,供后续工具调用使用。
  • 让渲染工具专注于呈现。不要在渲染处理函数中混入业务逻辑。
  • 在渲染工具的描述中说明调用依赖关系(例如“务必先调用 roll_dice”)。
  • 仅在确有需要时重新运行工具。对于“重新掷骰子”等局部交互,让 UI 直接调用数据工具,无需重新挂载小组件。

解耦示例

以下示例将掷骰子和渲染结果拆分为两个工具:

注册小组件资源
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;

管理状态

MCP 服务器提供的 UI 涉及三类状态:

状态类型 归属 生命周期 示例
业务数据(权威数据) MCP 服务器或外部服务 长期有效 任务、工单、文档
UI 状态(临时) UI 实例 UI 实例处于活动状态期间 选中的行、展开的面板、排序方式
跨会话状态(持久) 您控制的存储系统 跨会话、跨对话 已保存的筛选条件、视图模式、工作空间

每个值都应保存在负责管理它的系统中。UI 应根据工具结果中的权威数据进行渲染,并在此基础上应用临时的呈现状态。

MCP 服务器或外部服务
│
├── 权威业务数据
│
▼
UI
│
├── 临时呈现状态
│
└── 渲染后的视图 = 业务数据 + UI 状态

将业务数据保存在服务器上

以业务数据为准。不要只将它保存在 UI 中。用户执行操作时:

  1. UI 调用 MCP 工具。
  2. 服务器验证请求并更新数据。
  3. 服务器返回更新后的权威数据快照。
  4. 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 列表组件截图
  • Pizzaz 轮播: 使用 Embla 实现横向滚动,展示如何布局大量媒体内容。
    Pizzaz 轮播组件截图
  • Pizzaz 地图: 集成 Mapbox,支持全屏查看详情并与主机同步状态。
    Pizzaz 地图组件截图
  • Pizzaz 相册: 使用层叠式图库视图,方便用户详细了解某个地点。
    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"],
            },
          },
        },
      },
    ],
  })
);

仅将资源 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);

结账流程分为四步:

  1. MCP 工具在 structuredContent 中返回结账会话。
  2. 组件显示订单明细、总额、条款和履约选项。
  3. 用户选择付款后,组件调用 requestCheckout(checkoutSession)。
  4. ChatGPT 将所选的支付令牌发送给 MCP 服务器的 complete_checkout 工具。该工具通过相应的付款方式扣款,并返回已完成的订单。

结账会话必须包含:

  • 唯一的会话 ID。
  • 订单明细及各项数量。
  • 以货币最小单位表示的整数总额。
  • 支付服务商和商家的元数据。
  • 必需的法律、隐私、退款和客户支持链接。

价格和订单状态以服务器数据为准。请验证支付令牌,确保操作具有幂等性,持久化保存订单,并返回以服务器数据为准的收据。切勿信任仅由组件计算的总额。

使用 payment_mode: "test" 测试端到端流程,无需实际划转资金。在组件中处理取消付款、付款被拒和支付服务商报错的情况。

有关结账会话的完整字段、支付服务商的行为、complete_checkout 的结果结构以及委托支付的要求,请参阅结账 API 参考。