概述
插件开发者自行决定如何通过插件获得收入。目前,推荐且已普遍开放的方式是使用外部结账,让用户在开发者自己的域名下完成购买。现阶段,我们仅批准用于购买实物商品的插件,并正在努力支持更多商业场景。
我们也在向部分交易平台合作伙伴开放通过 ChatGPT 支付面板进行嵌入式结账的功能(测试版),并计划逐步向更多交易平台和实物商品零售商开放。在此之前,我们建议您引导用户通过您常规的外部结账流程完成购买。
推荐的变现方式
✅ 外部结账(推荐)
外部结账是指引导用户离开 ChatGPT,在您自己的网站或应用中进入由商家托管的结账流程。您负责处理符合条件的实物商品的定价、收款、配送和订单履约。
我们建议大多数插件开发者采用这种方式。
工作流程
- 用户在 ChatGPT 中与您的插件界面交互。
- 插件界面展示符合条件的实物商品,例如为商品提供“立即购买”操作。
- 用户决定购买后,插件界面通过链接或重定向引导用户离开 ChatGPT,进入您的外部结账流程。
- 您在自己的域名下处理所有支付、账单、税费、退款和合规事项。
- 购买完成后,用户可以带着订单确认信息或物流跟踪信息返回 ChatGPT。
使用已保存的支付方式结账
插件开发者可以在可选界面中构建结账流程,让客户使用先前在商家处保存的支付方式。此流程只能显示已保存的支付方式,不能向客户收集新支付方式的凭据。
采用这种方式时,客户无需跳转到 ChatGPT 以外的界面即可完成购买。
工作流程
- 用户在 ChatGPT 中与您的插件界面交互。
- 插件界面展示符合条件的实物商品及相应的汇总金额。
- 插件界面显示客户已在您处保存且可用于此次购买的支付方式。
- 客户选择已保存的支付方式,并在 ChatGPT 中确认购买。
- 您的服务器使用该支付方式处理交易,并向插件返回确认信息。
使用 ChatGPT 支付面板结账(内测版)
目前,仅部分交易平台可使用 ChatGPT 支付面板结账,此功能尚未向所有用户开放。
要在结账流程中收集新的支付方式,插件开发者必须使用 ChatGPT 支付面板。调用 requestCheckout 并传入结账会话数据(商品明细、汇总金额和已保存的支付方式),即可打开面板。当用户选择购买时,ChatGPT 会通过 complete_checkout 工具调用向您的 MCP 服务器发送一个代表所选支付方式的令牌。通过已集成的支付服务提供商(PSP)使用该令牌收款,然后通过 complete_checkout 返回最终订单详情。
流程概览
- 服务器准备会话。MCP 工具在
structuredContent中返回结账会话数据,包括会话 ID、商品明细、汇总金额和支付服务提供商。 - 小组件展示购物车预览。小组件显示商品明细和汇总金额,供用户确认。
- 小组件调用
requestCheckout。小组件调用requestCheckout(session_data)。ChatGPT 打开支付面板,显示待支付金额和多种支付方式。 - 服务器完成订单处理。用户点击支付按钮后,小组件通过调用
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。
Go 示例使用 github.com/modelcontextprotocol/go-sdk/mcp,版本为 v1.8.0。请将示例保存为 Go 模块中的 main.go,然后运行 go run .。该示例返回预设的本地结账数据,不会处理付款。
Ruby 示例使用 mcp gem,版本为 1.10.0。请将示例保存到文件中,再使用 Ruby 运行该文件。
本地测试夹具接受 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 支付面板发起的付款。
- Adyen
- Checkout.com
- Fiserv
- PayPal
- Stripe
- Worldpay
接收支付方式的原始数据(可选)
如果您是持有 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 设置不同的值。有关详情,请参阅支付服务提供商的变现指南。
实现检查清单
- 定义结账会话模型,其中应包含 ID、支付服务提供商对象、商品明细、汇总金额和法律条款链接。
- 通过 MCP 工具返回会话,将会话数据放在
structuredContent中,与小组件模板一同返回。 - 在小组件中渲染会话,供用户核对商品、汇总金额和条款。
- 用户发起结账时,调用
requestCheckout(session_data),并处理返回的订单或错误。 - 向用户收款。实现
complete_checkoutMCP 工具,让该工具处理扣款并返回符合结账规范的响应。 - 使用符合实际情况的金额、税费和折扣进行端到端测试,确认宿主显示的汇总金额符合预期。