ACP für Händler integrieren: Checkout-Sitzungen, delegierte Tokens und sichere Wiederholungen

Worum es geht

Stand: 25. Oktober 2026. Dieser Artikel bezieht sich auf den datierten ACP-Spezifikationsstand 2026-04-17 und dessen Änderungsprotokoll. Vor der Integration die vereinbarte API-Version, die Schemas der Payment Handler und die Versionshinweise erneut prüfen. Beispiele von einer älteren Website-Seite oder aus dem Verzeichnis für unveröffentlichte Fassungen im Repository nicht stillschweigend als Ersatz verwenden.

Die Agentic Checkout API bietet Händlern eine programmatische Checkout-Schnittstelle: Eine Sitzung lässt sich anlegen, aktualisieren oder abrufen, abschliessen oder abbrechen. Der Händler liefert den massgeblichen Warenkorbzustand zurück. Ein Agent kann Änderungen anfordern und dem Käufer das Ergebnis vorlegen; die Checkout-Berechnung und Bestellverarbeitung liegen dabei beim Backend des Händlers.

Warum es wichtig ist

Die Einigung über den Checkout und die Delegation von Zahlungszugangsdaten sind getrennte Vorgänge. Die Delegate Payment API tokenisiert Zahlungszugangsdaten zur eingeschränkten Verwendung durch den Zahlungsdienstleister des Händlers. Ihre Antwort enthält die Kennung eines Vault-Tokens. Die zugehörige Berechtigung umfasst einen Höchstbetrag, die Währung, die Kennung der Checkout-Sitzung, die Händlerkennung und den Ablaufzeitpunkt; als Verwendungszweck ist one_time dokumentiert.

Dieses Token ist keine allgemeine Einkaufserlaubnis für den Agenten. Händler und Zahlungsanbieter müssen den vereinbarten Handler integrieren und dessen Einschränkungen durchsetzen. Als defensive Implementierungsmassnahme die Erfassung von Zahlungszugangsdaten und die Token-Ausstellung in dedizierten Zahlungskomponenten halten, ausserhalb von Modell-Prompts und gewöhnlichen Anfrageprotokollen.

So wird es angewendet

• Die Sitzungsoperationen bereitstellen. Das Anlegen unter /checkout_sessions, das Abrufen und Aktualisieren an der Sitzungsressource sowie die Operationen /complete und /cancel implementieren. Aktuelle Gesamtbeträge, Informationen zur Auftragsabwicklung, Meldungen und Status zurückgeben. Die Unterscheidung zwischen ready_for_payment, authentication_required, complete_in_progress und completed beibehalten.
• Die Zahlungsverarbeitung abstimmen. Den vom Checkout angebotenen Handler verwenden und die Zahlungsdaten für den Abschluss gemäss dessen handler_id und Schema für das Zahlungsinstrument senden. Ein Vault-Token allein ist keine vollständige Checkout-Anfrage. Vor der Aktivierung dieses Zahlungswegs bestätigen, dass der Anbieter das Token verarbeiten kann.
• Die Integration authentifizieren. Die Sicherheitsdokumentation schreibt HTTPS und die Authentifizierung mit Bearer-Token vor. Den erforderlichen Header API-Version gemäss der gewählten Schnittstellenvereinbarung mitsenden; Sitzungszugriffe innerhalb der authentifizierten Beziehung zwischen Händler und Agent autorisieren.
• Sichere Wiederholungen implementieren. Diese Version verlangt Idempotency-Key bei POST-Anfragen. Einen Schlüssel nur für dieselbe Operation mit demselben Anfragekörper erneut verwenden. Fehlende Schlüssel führen zu idempotency_key_required; eine doppelte Anfrage bei noch laufender Verarbeitung führt zu idempotency_in_flight; ein veränderter Anfragekörper bei gleichem Schlüssel führt zu idempotency_conflict.
• Bestellbenachrichtigungen verifizieren. Die Version definiert die Webhook-Authentifizierung mit Merchant-Signature über den Zeitstempel und den unveränderten Anfragekörper sowie Prüfungen des zulässigen Zeitfensters zum Schutz vor Replay-Angriffen. Authentifizierte Aktualisierungen dem Checkout und der Bestellung zuordnen, bevor der lokale Zustand der Auftragsabwicklung geändert wird.

Stolpersteine

Ein erfolgreicher HTTP-Aufruf bedeutet nicht, dass die Sitzung abgeschlossen ist. Ein betrieblicher Abgleich sollte nach Unterbrechungen die Zustände von Checkout, Zahlung und Bestellung vergleichen, statt sofort einen weiteren Kauf auszulösen.

Die datierte Version schreibt Idempotenz vor, obwohl ältere Dokumentation sie als optional beschreibt. Die Schemas auf eine feste Version festlegen und diese Regel ausdrücklich testen. Tokenisierung, Käuferbestätigung, Zahlungsautorisierung und Auftragsabwicklung benötigen jeweils eigene Nachweise; keiner dieser Schritte sollte allein aus einer Erfolgsmeldung im Gespräch abgeleitet werden.