Den HTTP-Austausch von x402 v2 implementieren: Header, Facilitators und Zahlungsabwicklung

Worum es geht

Stand: 25. Oktober 2026. Beschrieben werden Version 2 des x402-Protokolls und dessen HTTP-Anbindung. Vor einem Deployment beide Spezifikationen und das gewählte Zahlungsschema erneut prüfen; die Protokollversion allein legt nicht alle Implementierungsdetails fest. RFC 9110 reserviert HTTP 402 für eine künftige Verwendung: Der Statuscode selbst definiert kein interoperables Zahlungsverfahren.

x402 ergänzt ein solches Verfahren. Ein Client fordert eine Ressource an, der Ressourcenserver liefert die Zahlungsanforderungen, und ein Facilitator kann die Prüfung und Zahlungsabwicklung über /verify und /settle übernehmen. Der Server kann diese Funktionen auch selbst bereitstellen. Der Facilitator muss das gewählte Schema und Netzwerk unterstützen.

Warum es wichtig ist

Die HTTP-Anbindung überträgt base64-codiertes JSON in drei Headern: PAYMENT-REQUIRED für die Zahlungsaufforderung des Servers, PAYMENT-SIGNATURE für die Zahlungsdaten des Clients und PAYMENT-RESPONSE für die Ergebnisse der Zahlungsabwicklung. Massgeblich ist der Header mit der Zahlungsaufforderung; ein Client sollte sich nicht auf einen bequem nutzbaren JSON-Antwortkörper verlassen.

Die Kernspezifikation trennt die Prüfung der Autorisierung vom Geldtransfer. Im standardmässigen Ablauf authorization erfolgt die Prüfung vor der Ausführung der angeforderten Operation und die Zahlungsabwicklung danach. Andere definierte Abläufe, darunter upfront und escrow, binden die Mittel vor der Ausführung. Eine erfolgreiche Prüfung reicht daher nicht als Nachweis aus, dass die Zahlung abgewickelt wurde.

So wird es angewendet

• Den Client gezielt implementieren. PaymentRequired auswerten, einen unterstützten Eintrag aus accepts auswählen und vor dem Signieren Betrag, Vermögenswert, Netzwerk und Empfänger mit den Ausgabenrichtlinien abgleichen. Die daraus resultierenden Zahlungsdaten über PAYMENT-SIGNATURE senden. Unbekannte Zahlungsabläufe ablehnen, statt ihre Wirkung zu erraten.
• Serverseitige Prüfungen implementieren. Die Anforderungen bereitstellen und die zurückgelieferte Autorisierung dagegen prüfen. Die Reihenfolge von Prüfung und Zahlungsabwicklung des gewählten Ablaufs einhalten. Das Abwicklungsergebnis in PAYMENT-RESPONSE zurückgeben; die darin enthaltene Transaktionskennung und das Netzwerk für den späteren Abgleich aufbewahren.
• Die Browser-Infrastruktur prüfen. Für Clients mit ursprungsübergreifenden Zugriffen PAYMENT-REQUIRED und PAYMENT-RESPONSE über CORS zugänglich machen und PAYMENT-SIGNATURE in der Preflight-Anfrage erlauben. Ein Test über die Kommandozeile prüft diese Browser-Beschränkungen nicht.
• Mit ungewissen Ergebnissen umgehen. Das dokumentierte Ergebnis settlement_pending bedeutet, dass eine bereits gesendete Transaktion noch bestätigt werden kann. Den Status anhand ihrer Transaktionskennung abgleichen, bevor über eine weitere Zahlung entschieden wird.
• Eine Checkliste für die Prüfung verwenden. Als Vorgehen bei der Integration festhalten, welche Komponente für Preisfestlegung, Signieren, Prüfung, Zahlungsabwicklung und Bereitstellung verantwortlich ist. Abgelehnte Zahlungen, nicht verfügbare Facilitators und verlorene Antworten in einer Nichtproduktionsumgebung erproben, bevor ein Agent die Befugnis erhält, Geld auszugeben.

Stolpersteine

Wer jede 402-Antwort als Erlaubnis zum Geldausgeben behandelt, verwechselt die Aufforderung eines Verkäufers mit der Autorisierung durch den Nutzer. Diese Autorisierung separat verwalten. Die Kernspezifikation schliesst die Budgetverwaltung auf Clientseite ausdrücklich aus.

Für die betriebliche Prüfung Zahlungsergebnis und Bereitstellung der Ressource getrennt dokumentieren. Bei einer bezahlten Anfrage ohne erfolgte Bereitstellung zunächst die Ursache untersuchen, bevor eine weitere Autorisierung erteilt wird. Diese Empfehlungen zur Dokumentation sind Implementierungspraxis; sie besagen nicht, dass HTTP automatische Rückerstattungen oder eine genau einmalige Ausführung in der Anwendung gewährleistet.