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

结账 API 参考

在可选的插件界面中实现结账功能。

概述

插件开发者自行决定如何通过插件获得收入。目前,推荐且已普遍开放的方式是使用外部结账,让用户在开发者自己的域名下完成购买。现阶段,我们仅批准用于购买实物商品的插件,并正在努力支持更多商业场景。

我们也在向部分交易平台合作伙伴开放通过 ChatGPT 支付面板进行嵌入式结账的功能(测试版),并计划逐步向更多交易平台和实物商品零售商开放。在此之前,我们建议您引导用户通过您常规的外部结账流程完成购买。

推荐的变现方式

✅ 外部结账(推荐)

外部结账是指引导用户离开 ChatGPT,在您自己的网站或应用中进入由商家托管的结账流程。您负责处理符合条件的实物商品的定价、收款、配送和订单履约。

我们建议大多数插件开发者采用这种方式。

工作流程

  1. 用户在 ChatGPT 中与您的插件界面交互。
  2. 插件界面展示符合条件的实物商品,例如为商品提供“立即购买”操作。
  3. 用户决定购买后,插件界面通过链接或重定向引导用户离开 ChatGPT,进入您的外部结账流程。
  4. 您在自己的域名下处理所有支付、账单、税费、退款和合规事项。
  5. 购买完成后,用户可以带着订单确认信息或物流跟踪信息返回 ChatGPT。

使用已保存的支付方式结账

插件开发者可以在可选界面中构建结账流程,让客户使用先前在商家处保存的支付方式。此流程只能显示已保存的支付方式,不能向客户收集新支付方式的凭据。

采用这种方式时,客户无需跳转到 ChatGPT 以外的界面即可完成购买。

工作流程

  1. 用户在 ChatGPT 中与您的插件界面交互。
  2. 插件界面展示符合条件的实物商品及相应的汇总金额。
  3. 插件界面显示客户已在您处保存且可用于此次购买的支付方式。
  4. 客户选择已保存的支付方式,并在 ChatGPT 中确认购买。
  5. 您的服务器使用该支付方式处理交易,并向插件返回确认信息。

使用 ChatGPT 支付面板结账(内测版)

目前,仅部分交易平台可使用 ChatGPT 支付面板结账,此功能尚未向所有用户开放。

要在结账流程中收集新的支付方式,插件开发者必须使用 ChatGPT 支付面板。调用 requestCheckout 并传入结账会话数据(商品明细、汇总金额和已保存的支付方式),即可打开面板。当用户选择购买时,ChatGPT 会通过 complete_checkout 工具调用向您的 MCP 服务器发送一个代表所选支付方式的令牌。通过已集成的支付服务提供商(PSP)使用该令牌收款,然后通过 complete_checkout 返回最终订单详情。

流程概览

  1. 服务器准备会话。MCP 工具在 structuredContent 中返回结账会话数据,包括会话 ID、商品明细、汇总金额和支付服务提供商。
  2. 小组件展示购物车预览。小组件显示商品明细和汇总金额,供用户确认。
  3. 小组件调用 requestCheckout。小组件调用 requestCheckout(session_data)。ChatGPT 打开支付面板,显示待支付金额和多种支付方式。
  4. 服务器完成订单处理。用户点击支付按钮后,小组件通过调用 complete_checkout 工具将请求发回您的 MCP 服务器。MCP 工具返回已完成的订单,小组件会在 requestCheckout 的响应中收到该订单。

结账会话

您负责构建供宿主渲染的结账会话载荷。id 和 payment_provider 等字段的具体值取决于您的支付服务提供商和商务系统。您的 MCP 工具应返回以下内容。

  • 用户购买的商品明细及数量。
  • 与服务器计算结果一致的汇总金额(小计、税额、折扣、费用和总计)。
  • 集成 PSP 所需的提供商元数据。
  • 法律条款和政策的链接(如使用条款、退款政策)。

在小组件中调用 requestCheckout

宿主提供 window.openai.requestCheckout。用户发起购买时,使用它打开 ChatGPT 支付面板。

以下是调用示例。

async function handleCheckout(sessionJson: string) {
  const session = JSON.parse(sessionJson);

  if (!window.openai?.requestCheckout) {
    throw new Error("requestCheckout is not available in this host");
  }

  // Host opens the ChatGPT payment sheet.
  const order = await window.openai.requestCheckout({
    ...session,
    id: String(session.id), // Use a unique ID for every checkout session.
  });

  return order; // Host returns the order payload.
}

您可以在组件中通过按钮点击事件发起结账。

import { useState } from "react";

function CheckoutButton({
  checkoutSessionJson,
}: {
  checkoutSessionJson: string;
}) {
  const [isLoading, setIsLoading] = useState(false);
  const [order, setOrder] = useState<Record<string, unknown> | null>(null);
  const checkoutButton = (
    <button
      onClick={async () => {
        setIsLoading(true);
        try {
          const orderResponse = await handleCheckout(checkoutSessionJson);
          setOrder(orderResponse);
        } catch (error) {
          console.error(error);
        } finally {
          setIsLoading(false);
        }
      }}
    >
      {isLoading ? "Loading..." : "Checkout"}
    </button>
  );
  return (
    <>
      {checkoutButton}
      <pre>{JSON.stringify(order, null, 2)}</pre>
    </>
  );
}

下面是小组件可传给宿主的完整结账会话示例。您的插件提供示例中的结账会话字段。ChatGPT 会添加由宿主管理的字段,例如 merchant、logo_url、conversation_id、connector_id 和 ecosystem_app_uri。请将 merchant_id 字段设为您的 PSP 指定的值。

const checkoutRequest = {
  id: "checkout_session_123",
  payment_provider: {
    provider: "stripe",
    merchant_id: "merchant_123",
    supported_payment_methods: [
      {
        type: "card",
        allowed_card_brands: ["visa", "mastercard"],
      },
      { type: "apple_pay" },
      { type: "google_pay" },
    ],
    managed_payment_methods: [
      {
        type: "card",
        id: "pm_123",
        display_name: "Visa ending in 4242",
        display_last4: "4242",
        display_brand: "visa",
      },
    ],
  },
  payment_mode: "live",
  status: "ready_for_payment",
  currency: "USD",
  metadata: {
    cart_id: "cart_123",
    merchant_order_reference: "order_ref_123",
  },
  line_items: [
    {
      id: "line_item_123",
      item: {
        id: "item_123",
        quantity: 1,
      },
      name: "Canvas backpack",
      description: "A weather-resistant everyday backpack.",
      images: ["https://merchant.example.com/images/canvas-backpack.png"],
      base_amount: 3000,
      discount: 0,
      subtotal: 3000,
      tax: 300,
      total: 3300,
    },
  ],
  totals: [
    {
      type: "items_base_amount",
      display_text: "Items subtotal",
      amount: 3000,
    },
    {
      type: "subtotal",
      display_text: "Subtotal",
      amount: 3000,
    },
    {
      type: "fulfillment",
      display_text: "Shipping",
      amount: 550,
    },
    {
      type: "tax",
      display_text: "Tax",
      amount: 300,
    },
    {
      type: "total",
      display_text: "Total",
      amount: 3850,
    },
  ],
  fulfillment_options: [
    {
      id: "standard_shipping",
      type: "shipping",
      title: "Standard shipping",
      subtitle: "Arrives in 3-5 business days",
      carrier: "USPS",
      earliest_delivery_time: "2027-01-15T15:00:00Z",
      latest_delivery_time: "2027-01-19T18:00:00Z",
      subtotal: 500,
      tax: 50,
      total: 550,
    },
  ],
  fulfillment_option_id: "standard_shipping",
  fulfillment_address: {
    name: "Jane Customer",
    line_one: "123 Main St",
    line_two: "Apt 4B",
    city: "San Francisco",
    state: "CA",
    country: "US",
    postal_code: "94107",
    phone_number: "+14155550123",
  },
  messages: [
    {
      type: "info",
      param: "fulfillment_address",
      content_type: "plain",
      content: "Free returns within 30 days.",
    },
  ],
  links: [
    { type: "terms_of_use", url: "https://merchant.example.com/terms" },
    { type: "privacy_policy", url: "https://merchant.example.com/privacy" },
    { type: "support_url", url: "https://merchant.example.com/support" },
  ],
};

const response = await window.openai.requestCheckout(checkoutRequest);

实现时请注意以下几点。

  • window.openai.requestCheckout(session) 会打开宿主的结账界面。
  • 成功时,Promise 会兑现并返回订单结果。发生错误或用户取消时,Promise 会被拒绝。
  • 根据会话 JSON 渲染界面,供用户核对付款内容。
  • 所有金额字段都应以货币的最小单位表示,且必须为整数。
  • 使用 payment_provider.managed_payment_methods 提供客户已在商家处保存的支付方式。
  • metadata 中的值应保持为字符串。
  • 将集成所要求的 PSP Slug 填入 provider,并向您的 PSP 查询 merchant_id 的值。

在 MCP 服务器上提供 complete_checkout 工具

您可以参照以下示例,将其中的处理逻辑替换为自己的实现。

要运行此 Python 示例,请先安装 fastmcp 和 pydantic。工具通过 output_schema 声明 MCP 的 outputSchema。ToolResult.structured_content 提供 structuredContent,meta 提供 _meta。

本地测试夹具接受 example-session 和 example-payment-token 并返回示例响应,期间不会扣款或创建订单。

注册结账工具
from typing import Any, Literal

from fastmcp import FastMCP
from fastmcp.tools.tool import ToolResult
from pydantic import BaseModel

server = FastMCP("Checkout response fixture")
META_SESSION_ID = "openai/checkoutSessionId"


class Buyer(BaseModel):
    email: str


class PaymentData(BaseModel):
    # Deliberately accepts only a local fixture token, never real payment credentials.
    token: Literal["example-payment-token"]


class CompleteCheckoutOutput(BaseModel):
    id: str
    status: str
    currency: str
    line_items: list[dict[str, Any]]
    fulfillment_address: dict[str, Any]
    fulfillment_options: list[dict[str, Any]]
    fulfillment_option_id: str
    totals: list[dict[str, Any]]
    order: dict[str, Any]


@server.tool(
    description="Return the local checkout response fixture; does not charge a payment method or create a real order.",
    output_schema=CompleteCheckoutOutput.model_json_schema(),
)
async def complete_checkout(
    checkout_session_id: str,
    buyer: Buyer,
    payment_data: PaymentData,
) -> ToolResult:
    if checkout_session_id != "example-session":
        raise ValueError("This response fixture only accepts example-session")
    return ToolResult(
        content=[],
        structured_content={
            "id": checkout_session_id,
            "status": "completed",
            "currency": "USD",
            "line_items": [
                {
                    "id": "line_item_1",
                    "item": {
                        "id": "item_1",
                        "quantity": 1,
                    },
                    "base_amount": 3000,
                    "discount": 0,
                    "subtotal": 3000,
                    "tax": 300,
                    "total": 3300,
                },
            ],
            "fulfillment_address": {
                "name": "Jane Customer",
                "line_one": "123 Main St",
                "line_two": "Apt 4B",
                "city": "San Francisco",
                "state": "CA",
                "country": "US",
                "postal_code": "94107",
                "phone_number": "+1 (555) 555-5555",
            },
            "fulfillment_options": [
                {
                    "id": "fulfillment_option_1",
                    "type": "shipping",
                    "title": "Standard shipping",
                    "subtitle": "3-5 business days",
                    "carrier": "USPS",
                    "earliest_delivery_time": "2026-02-24T15:00:00Z",
                    "latest_delivery_time": "2026-02-28T18:00:00Z",
                    "subtotal": 0,
                    "tax": 0,
                    "total": 0,
                },
            ],
            "fulfillment_option_id": "fulfillment_option_1",
            "totals": [
                {
                    "type": "items_base_amount",
                    "display_text": "Items subtotal",
                    "amount": 3000,
                },
                {
                    "type": "subtotal",
                    "display_text": "Subtotal",
                    "amount": 3000,
                },
                {
                    "type": "tax",
                    "display_text": "Tax",
                    "amount": 300,
                },
                {
                    "type": "total",
                    "display_text": "Total",
                    "amount": 3300,
                },
            ],
            "order": {
                "id": "order_id_123",
                "checkout_session_id": checkout_session_id,
                "permalink_url": "",
            },
        },
        meta={META_SESSION_ID: "checkout-flow"},
        is_error=False,
    )

请根据您的系统调整示例,以完成以下操作。

  • 对接您的支付服务提供商,使用 payment_data 中的支付方式扣款。
  • 将订单持久化保存到您的系统中。
  • 返回以您的系统记录为准的订单或收据数据。
  • 如果要渲染订单确认小组件,请包含 _meta.ui.resourceUri(为保持兼容,ChatGPT 也支持可选别名 _meta["openai/outputTemplate"])。

以下支付服务提供商支持处理通过 ChatGPT 支付面板发起的付款。

接收支付方式的原始数据(可选)

如果您是持有 PCI DSS 1 级证书的商家,可以实现 Agentic Commerce Protocol 的 Delegate Payment 端点,直接接收支付方式的原始数据。委托支付请求会包含您的支付流程所需的完整支付方式详情,包括原始卡号、有效期、CVC、账单地址、支付授权限制、风险信号和元数据。

以下是包含银行卡原始数据的支付方式请求示例。

{
  "payment_method": {
    "type": "card",
    "card_number_type": "fpan",
    "number": "4242424242424242",
    "exp_month": "11",
    "exp_year": "2026",
    "name": "Jane Doe",
    "cvc": "223",
    "checks_performed": ["avs", "cvv"],
    "iin": "424242",
    "display_card_funding_type": "credit",
    "display_brand": "visa",
    "display_last4": "4242",
    "metadata": {}
  },
  "allowance": {
    "reason": "one_time",
    "max_amount": 5000,
    "currency": "usd",
    "checkout_session_id": "cs_01HV3P3ABC123",
    "merchant_id": "acme_corp",
    "expires_at": "2026-02-13T12:00:00Z"
  },
  "billing_address": {
    "name": "Jane Doe",
    "line_one": "185 Berry Street",
    "line_two": "Suite 550",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94107"
  },
  "risk_signals": [
    {
      "type": "card_testing",
      "score": 5,
      "action": "authorized"
    }
  ],
  "metadata": {
    "session_id": "sess_abc123",
    "user_agent": "ChatGPT/2.0"
  }
}

响应应返回一个代表该支付方式的 ID。调用 complete_checkout 时,会将此 ID 作为 payment_data 的一部分传入。

{
  "id": "vt_01J8Z3WXYZ9ABC123",
  "created": "2026-02-12T14:30:00Z",
  "metadata": {
    "source": "agent_checkout",
    "merchant_id": "acme_corp",
    "idempotency_key": "idem_xyz789"
  }
}

错误处理

complete_checkout 工具调用可以返回类型为 error 的消息。如果错误消息的 code 为 payment_declined 或 requires_3ds,ChatGPT 会在支付面板上显示该消息。所有其他错误消息都会作为 requestCheckout 的响应返回给小组件。小组件可以按需显示错误。

测试支付模式

要启用测试支付模式,请将 payment_mode 字段设为 test,并在调用 requestCheckout 时传入该设置。ChatGPT 随后会打开支持测试卡(例如 4242 测试卡)的支付面板。生成的 token 会随 payment_data 传给 complete_checkout 工具,您可以在 PSP 的预发布环境中处理该令牌。这样即可测试端到端流程,无需实际划转资金。

在测试支付模式下,您可能需要为 merchant_id 设置不同的值。有关详情,请参阅支付服务提供商的变现指南。

实现检查清单

  1. 定义结账会话模型,其中应包含 ID、支付服务提供商对象、商品明细、汇总金额和法律条款链接。
  2. 通过 MCP 工具返回会话,将会话数据放在 structuredContent 中,与小组件模板一同返回。
  3. 在小组件中渲染会话,供用户核对商品、汇总金额和条款。
  4. 用户发起结账时,调用 requestCheckout(session_data),并处理返回的订单或错误。
  5. 向用户收款。实现 complete_checkout MCP 工具,让该工具处理扣款并返回符合结账规范的响应。
  6. 使用符合实际情况的金额、税费和折扣进行端到端测试,确认宿主显示的汇总金额符合预期。