Überblick
Wenn du ein Plugin entwickelst, entscheidest du selbst, wie du damit Einnahmen erzielst. Derzeit ist der empfohlene und allgemein verfügbare Ansatz der externe Checkout. Dabei schließt deine Kundschaft den Kauf auf deiner eigenen Domain ab. Aktuell lassen wir nur Plugins für den Kauf physischer Waren zu. Wir arbeiten daran, weitere Anwendungsfälle im Handel zu unterstützen.
Ausgewählten Partnerunternehmen, die Online-Marktplätze betreiben, ermöglichen wir außerdem einen integrierten Checkout mit dem Zahlungsdialog von ChatGPT (Beta). Wir planen, den Zugang nach und nach auf weitere Marktplätze und Einzelhandelsunternehmen auszuweiten, die physische Waren verkaufen. Bis dahin empfehlen wir, Kaufinteressierte zu deinem üblichen externen Checkout weiterzuleiten.
Empfohlener Ansatz zur Monetarisierung
✅ Externer Checkout (empfohlen)
Beim externen Checkout leitest du Kaufinteressierte von ChatGPT zu einem von deinem Unternehmen gehosteten Checkout auf deiner Website oder in deiner Anwendung weiter. Dort legst du die Preise für zugelassene physische Waren fest und kümmerst dich um Zahlungen, Versand und Bestellabwicklung.
Diesen Ansatz empfehlen wir den meisten, die Plugins entwickeln.
So funktioniert es
- Eine Person nutzt die Oberfläche deines Plugins in ChatGPT.
- Die Plugin-Oberfläche zeigt zugelassene physische Waren an, zum Beispiel mit einer Schaltfläche „Jetzt kaufen“.
- Entscheidet sich die Person für den Kauf, führt ein Link oder eine Weiterleitung in der Plugin-Oberfläche von ChatGPT zu deinem externen Checkout.
- Zahlungen, Abrechnung, Steuern und Erstattungen wickelst du vollständig auf deiner Domain ab. Dort bist du auch für die Einhaltung der geltenden Vorschriften verantwortlich.
- Nach dem Kauf kann die Person mit der Bestellbestätigung oder den Angaben zur Sendungsverfolgung zu ChatGPT zurückkehren.
Checkout mit gespeicherten Zahlungsmethoden
In der optionalen Plugin-Oberfläche kannst du einen Checkout anbieten, bei dem deine Kundschaft bereits bei dir gespeicherte Zahlungsmethoden verwendet. Dieser Checkout darf ausschließlich gespeicherte Zahlungsmethoden anzeigen. Daten für neue Zahlungsmethoden darfst du hier nicht erfassen.
So lässt sich der Kauf direkt in ChatGPT abschließen, ohne dass du die Person zu einer anderen Oberfläche weiterleiten musst.
So funktioniert es
- Eine Person nutzt die Oberfläche deines Plugins in ChatGPT.
- Die Plugin-Oberfläche zeigt zugelassene physische Waren mit den zugehörigen Summen an.
- Die Plugin-Oberfläche zeigt die für den Kauf zulässigen Zahlungsmethoden an, die die Person bereits bei dir gespeichert hat.
- Die Person wählt eine gespeicherte Zahlungsmethode aus und bestätigt den Kauf in ChatGPT.
- Dein Server wickelt den Kauf mit der gespeicherten Zahlungsmethode ab und gibt die Bestätigung an das Plugin zurück.
Checkout mit dem Zahlungsdialog von ChatGPT (private Beta)
Der Checkout mit dem Zahlungsdialog von ChatGPT ist derzeit auf ausgewählte Marktplätze beschränkt und steht noch nicht allen zur Verfügung.
Wenn du beim Checkout neue Zahlungsmethoden erfassen möchtest, musst du den Zahlungsdialog von ChatGPT verwenden. Rufe requestCheckout mit den Daten der Checkout-Sitzung (Bestellpositionen, Summen, gespeicherte Zahlungsmethoden) auf, um den Dialog zu öffnen. Sobald die Person den Kauf bestätigt, sendet ChatGPT über den Tool-Aufruf complete_checkout ein Token für die ausgewählte Zahlungsmethode an deinen MCP-Server. Ziehe den Betrag mit diesem Token über deine Integration mit dem Zahlungsdienstleister (PSP) ein. Gib anschließend die endgültigen Bestelldaten aus complete_checkout zurück.
Ablauf im Überblick
- Der Server bereitet die Sitzung vor. Ein MCP-Tool gibt die Daten der Checkout-Sitzung (Sitzungs-ID, Bestellpositionen, Summen, Zahlungsdienstleister) in
structuredContentzurück. - Das Widget zeigt den Warenkorb an. Es stellt die Bestellpositionen und Summen zur Prüfung und Bestätigung dar.
- Das Widget ruft
requestCheckoutauf. Dazu führt esrequestCheckout(session_data)aus. ChatGPT öffnet den Zahlungsdialog und zeigt den zu zahlenden Betrag sowie verschiedene Zahlungsmethoden an. - Der Server schließt die Bestellung ab. Sobald die Person auf die Schaltfläche zum Bezahlen klickt, ruft das Widget das Tool
complete_checkoutauf deinem MCP-Server auf. Das MCP-Tool gibt die abgeschlossene Bestellung zurück. Das Widget erhält sie als Antwort aufrequestCheckout.
Checkout-Sitzung
Du stellst die Daten der Checkout-Sitzung zusammen, die der Host anzeigt. Welche Werte Felder wie id und payment_provider enthalten müssen, hängt von deinem Zahlungsdienstleister und deinem Shopsystem ab. Dein MCP-Tool sollte folgende Daten zurückgeben:
- Die Bestellpositionen mit der jeweils bestellten Menge.
- Die Summen (Zwischensumme, Steuern, Rabatte, Gebühren und Gesamtbetrag), die mit den Berechnungen deines Servers übereinstimmen.
- Die Anbietermetadaten, die deine PSP-Integration benötigt.
- Links zu rechtlichen Informationen und Richtlinien, etwa zu den Geschäftsbedingungen und den Erstattungsbedingungen.
Im Widget requestCheckout aufrufen
Der Host stellt window.openai.requestCheckout bereit. Öffne damit den Zahlungsdialog von ChatGPT, sobald jemand einen Kauf einleitet.
Beispiel:
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.
}In deiner Komponente kannst du den Checkout beispielsweise per Klick auf eine Schaltfläche starten:
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>
</>
);
}Das folgende Beispiel zeigt eine vollständige Checkout-Sitzung, die dein Widget an den Host übergeben kann. Dein Plugin liefert die unten aufgeführten Sitzungsfelder. ChatGPT ergänzt die vom Host verwalteten Felder wie merchant, logo_url, conversation_id, connector_id und ecosystem_app_uri. Trage in merchant_id den Wert ein, den dein PSP vorgibt:
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);Wichtige Hinweise:
window.openai.requestCheckout(session)öffnet die Checkout-Oberfläche des Hosts.- Bei Erfolg liefert das Promise das Bestellergebnis. Bei einem Fehler oder Abbruch wird es abgelehnt.
- Stelle die Sitzungsdaten aus dem JSON im Widget dar, damit die Person prüfen kann, wofür sie bezahlt.
- Gib alle Beträge als ganze Zahlen in der kleinsten Einheit der jeweiligen Währung an.
- Verwende
payment_provider.managed_payment_methodsfür Zahlungsmethoden, die die Person bereits bei deinem Unternehmen gespeichert hat. - Speichere die Werte in
metadataals Zeichenketten. - Verwende für
providerden PSP-Slug, den deine Integration erfordert. Den Wert fürmerchant_iderhältst du von deinem PSP.
Das Tool complete_checkout auf dem MCP-Server bereitstellen
Du kannst das folgende Muster übernehmen und deine eigene Logik einsetzen.
Installiere fastmcp und pydantic, um dieses Python-Beispiel auszuführen. Mit output_schema deklariert das Tool das MCP-Ausgabeschema outputSchema. ToolResult.structured_content liefert den Wert für structuredContent und meta den Wert für _meta. Die lokale Test-Fixture akzeptiert example-session und example-payment-token und gibt eine Beispielantwort zurück, ohne eine Zahlungsmethode zu belasten oder eine Bestellung anzulegen.
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,
)Passe das Beispiel an deine Integration an:
- Binde deinen Zahlungsdienstleister an, um den Betrag über die in
payment_dataangegebene Zahlungsmethode einzuziehen. - Speichere die Bestellung dauerhaft in deinem System.
- Gib die maßgeblichen Bestell- und Belegdaten aus deinem System zurück.
- Gib
_meta.ui.resourceUrian, wenn du ein Bestätigungswidget anzeigen möchtest (aus Kompatibilitätsgründen akzeptiert ChatGPT auch_meta["openai/outputTemplate"]als optionalen Alias).
Die folgenden Zahlungsdienstleister unterstützen die Zahlungsabwicklung für den Zahlungsdialog von ChatGPT:
- Adyen
- Checkout.com
- Fiserv
- PayPal
- Stripe
- Worldpay
Optional: Rohdaten von Zahlungsmethoden direkt empfangen
Wenn dein Handelsunternehmen nach PCI DSS Level 1 zertifiziert ist, kannst du die Rohdaten einer Zahlungsmethode direkt empfangen. Implementiere dazu den Endpunkt Delegate Payment des Agentic Commerce Protocol. Die delegierte Zahlungsanfrage enthält sämtliche Angaben zur Zahlungsmethode, die du für die Zahlungsabwicklung benötigst. Dazu gehören die vollständige Kartennummer, das Ablaufdatum, der CVC, die Rechnungsadresse, die Grenzen der Zahlungsfreigabe, Risikosignale und Metadaten.
Eine Anfrage mit den Rohdaten einer Kartenzahlung sieht beispielsweise so aus:
{
"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"
}
}
Die Antwort sollte eine ID zurückgeben, die die Zahlungsmethode identifiziert. Das Tool complete_checkout erhält diese ID als Teil von payment_data.
{
"id": "vt_01J8Z3WXYZ9ABC123",
"created": "2026-02-12T14:30:00Z",
"metadata": {
"source": "agent_checkout",
"merchant_id": "acme_corp",
"idempotency_key": "idem_xyz789"
}
}
Fehlerbehandlung
Der Tool-Aufruf complete_checkout kann Meldungen vom Typ error zurückgeben. Hat code den Wert payment_declined oder requires_3ds, zeigt ChatGPT die Fehlermeldung im Zahlungsdialog an. Alle anderen Fehlermeldungen erhält das Widget als Antwort auf requestCheckout. Du kannst festlegen, wie das Widget den Fehler anzeigt.
Testmodus für Zahlungen
Setze das Feld payment_mode auf test, wenn du requestCheckout aufrufst, um den Testmodus zu verwenden. ChatGPT öffnet dann einen Zahlungsdialog, der Testkarten akzeptiert, etwa die 4242-Testkarte. Das so erzeugte token ist in payment_data enthalten und wird an das Tool complete_checkout übergeben. Du kannst es in der Staging-Umgebung deines PSP verarbeiten. So kannst du den gesamten Ablauf testen, ohne dass tatsächlich Geld fließt.
Im Testmodus musst du für merchant_id möglicherweise einen anderen Wert angeben. Einzelheiten findest du im Leitfaden zur Monetarisierung deines Zahlungsdienstleisters.
Checkliste für die Implementierung
- Definiere das Datenmodell für deine Checkout-Sitzung. Berücksichtige IDs, das Objekt für den Zahlungsdienstleister, Bestellpositionen, Summen und Links zu rechtlichen Informationen.
- Gib die Sitzungsdaten aus deinem MCP-Tool zurück. Verwende dafür
structuredContentund liefere auch die Widget-Vorlage mit. - Zeige die Sitzungsdaten im Widget an, damit deine Kundschaft die Artikel, Summen und Bedingungen prüfen kann.
- Rufe
requestCheckout(session_data)auf, wenn die Person den Kauf einleitet. Verarbeite die zurückgegebene Bestellung oder den Fehler. - Ziehe den Kaufbetrag ein. Implementiere dazu das MCP-Tool
complete_checkoutso, dass seine Antwort der Checkout-Spezifikation entspricht. - Teste den gesamten Ablauf mit realistischen Beträgen, Steuern und Rabatten. Prüfe dabei, ob der Host die erwarteten Summen anzeigt.