Bezahlte API-Aufrufe: Abwicklung, Ausführung und Lieferung trennen
Anleitungen
Erfasse Zahlung, Anbieterausführung, gespeichertes Ergebnis und Empfang beim Käufer als getrennte Zustände, bevor du erneut zahlst oder Erfolg meldest.
Eine x402-Abwicklung belegt, dass eine Zahlung angenommen wurde. Sie belegt für sich allein weder den Abschluss des Anbieterauftrags noch ein gespeichertes Ergebnis oder den Empfang beim Käufer. Ein verlässlicher Client und Verkäufer erfassen diese Schritte getrennt.
Beginne mit dem Zahlungsbeleg. Bewahre Ressource, Anfrage-Fingerprint, Zahlungsanforderung und Abwicklungsreferenz auf. Geht die Antwort nach der Zahlung verloren, gleiche genau diesen Kauf ab, statt eine neue Autorisierung zu erzeugen. Eine neue Zahlung ist ein neuer Kauf, auch wenn die beabsichtigte Aufgabe gleich aussieht.
Erfasse anschließend die Ausführung, ohne Unklarheit als Erfolg auszugeben. Ein Anbieter kann den Auftrag ablehnen, in ein Zeitlimit laufen oder nach der Zahlung einen unklaren Zustand liefern. Markiere den Kauf dann als ungeklärt und verhindere automatische Wiederholungen, die einen weiteren Anbieterauftrag oder eine weitere Belastung auslösen könnten.
Auch die Lieferung braucht einen eigenen Beleg. Das Ergebnis sollte vor der Erfolgsmeldung dem ursprünglichen Kauf zugeordnet gespeichert werden. Der Käufer bewahrt die Antwort oder eine private Abrufreferenz auf. Eine Transaktionsreferenz ohne zugehöriges Ergebnis bleibt ein Zahlungsbeleg und ist kein Lieferbeleg.
Nutze den Dienststatus als Signal für die Auswahl eines Dienstes und nicht als Beleg für einen einzelnen Kauf. Ein Prozess kann erreichbar sein, während Anbieterbereitschaft oder bezahlte Lieferung unbekannt sind. Meldet der Verkäufer eine Einschränkung, pausiere neue Autorisierungen und halte die private Wiederlieferung für frühere Käufer offen.
Bleibt ein Kauf ungeklärt, sende Kaufreferenz, Route und ungefähren Zeitpunkt an den Support des Verkäufers. Sende niemals einen Private Key oder eine Seed-Phrase. Starte erst dann mit einer frischen Zahlung, wenn der ursprüngliche Kauf abgeglichen oder bewusst geschlossen wurde.