如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
總覽 智慧體存取權 ChatGPT 與 Codex 使用者文件 使用案例

結帳 API 參考文件

在外掛程式的選用介面中實作結帳功能。

概覽

外掛程式開發者可自行決定如何透過外掛程式獲利。目前建議且已全面開放的做法是使用外部結帳,讓使用者在開發者自己的網域完成購買。目前我們只核准供使用者購買實體商品的外掛程式,並正積極擴大支援範圍,以涵蓋更多商務應用情境。

我們也已開放部分市集合作夥伴試用透過 ChatGPT 付款面板進行內嵌結帳的功能(Beta 版),並計畫逐步開放給更多市集和實體商品零售商。在此之前,建議您引導使用者透過既有的外部結帳流程完成購買。

建議的營利方式

✅ 外部結帳(建議)

外部結帳是指將使用者從 ChatGPT 導向您自己的網站或應用程式,進入由商家提供的結帳流程。符合資格的實體商品由您負責定價、收款、配送及履行訂單。

我們建議大多數外掛程式開發者採用這種方式。

運作方式

  1. 使用者在 ChatGPT 中操作您的外掛程式介面。
  2. 外掛程式介面顯示符合資格的實體商品,例如提供「立即購買」按鈕。
  3. 使用者決定購買時,外掛程式介面會提供連結,或直接將使用者從 ChatGPT 重新導向您的外部結帳流程。
  4. 付款、帳務、稅金、退款及法規遵循事宜均由您在自己的網域上處理。
  5. 購買完成後,使用者可帶著訂單確認資訊或配送追蹤資料返回 ChatGPT。

使用已儲存的付款方式結帳

外掛程式開發者可以在選用介面中建置結帳流程,讓顧客使用先前在商家儲存的付款方式。這個流程只能顯示已儲存的付款方式,不能向顧客收集新付款方式的憑證。

採用這種方式時,顧客可直接在 ChatGPT 中完成購買,無須前往其他介面。

運作方式

  1. 使用者在 ChatGPT 中操作您的外掛程式介面。
  2. 外掛程式介面顯示符合資格的實體商品及相關的合計金額。
  3. 外掛程式介面顯示顧客先前在您這裡儲存、可用於這筆交易的付款方式。
  4. 顧客在 ChatGPT 中選取已儲存的付款方式並確認購買。
  5. 您的伺服器使用該付款方式處理交易,並將確認資訊傳回外掛程式。

使用 ChatGPT 付款面板結帳(非公開 Beta 版)

目前只有部分市集可使用 ChatGPT 付款面板提供結帳服務,這項功能尚未對所有使用者開放。

如需在結帳流程中收集新的付款方式,外掛程式開發者必須使用 ChatGPT 付款面板。呼叫 requestCheckout 並傳入結帳工作階段資料(商品明細、各項合計金額、已儲存的付款方式),即可開啟面板。使用者選擇購買時,ChatGPT 會透過 complete_checkout 工具呼叫,將代表所選付款方式的權杖傳送至您的 MCP 伺服器。請透過您整合的支付服務供應商(PSP)使用這個權杖收款,然後透過 complete_checkout 傳回最終的訂單明細。

流程概覽

  1. 伺服器準備工作階段:MCP 工具在 structuredContent 中傳回結帳工作階段資料(工作階段 ID、商品明細、各項合計金額、支付服務供應商)。
  2. 小工具顯示購物車預覽:小工具顯示商品明細和各項合計金額,供使用者確認。
  3. 小工具呼叫 requestCheckout:小工具呼叫 requestCheckout(session_data)。ChatGPT 隨即開啟付款面板,顯示應付金額及多種付款方式。
  4. 伺服器完成訂單:使用者按下付款按鈕後,小工具會呼叫 MCP 伺服器上的 complete_checkout 工具。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 的值應一律使用字串。
  • 將 provider 設為整合時所需的 PSP Slug,並向 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. 進行端對端測試:使用符合實際情境的金額、稅金及折扣,確認主機顯示的各項合計金額符合預期。