PAYMENT-SIGNATURE und versucht die Anfrage dann erneut.
Der Unterschied besteht darin, dass die Bestellzahlung eine Plattform-API ist und ein Kontotoken benötigt; während die direkte Nutzung der AI-API von x402.acedata.cloud nur X402 verwenden kann und kein API-Token benötigt.
Bestellung vorbereiten
Gehe zur Ace Data Cloud-Konsole, wähle die zu zahlende Bestellung aus und notiere die Bestell-ID. Falls du noch keine Bestellung hast, kannst du auf der Tarifseite eine ausstehende Bestellung erstellen. Der Bestellpreis richtet sich nach der Anzeige auf der Seite;amount in der X402-402-Antwort ist die endgültige Grundlage für die Signatur.
Kontotoken erstellen
Anfragen zur Bestellzahlung benötigen ein Kontotoken. Öffne die Plattform-Token-Seite und erstelle ein Token im Formatplatform-v1-....
Verwende für nachfolgende Anfragen:
402 auslösen
Sende zunächst eine Anfrage ohnePAYMENT-SIGNATURE:
accepts:
x402Version ist 2, network verwendet die CAIP-2-Kennung und das Betragsfeld ist amount.
Programmausgabe beim Erstellen einer Bestellung über 10 Credits und beim Auslösen von 402:
Die folgenden Transaktionsaufzeichnungen sind historische, praktisch getestete Beispiele unter der alten Richtlinie; Beträge und Transaktions-Hashes bleiben unverändert. Neue X402-Bestellungen erhalten keinen Zahlungsart-Rabatt mehr; verwende bitte amount aus der aktuellen 402-Antwort als Grundlage für Signatur und Zahlung.
- Nach erfolgreicher Erstellung der Bestellung ist ihr Status
Pending; zu diesem Zeitpunkt gibt es noch keine On-Chain-Zahlung. - Die erste
pay/-Anfrage enthält keinePAYMENT-SIGNATUREund gibt daher HTTP 402 zurück. acceptsgibt gleichzeitig Baseexactund Solanaexactan; dieses Tutorial wählt im Folgenden Base.- Der Preis bei der Bestellungserstellung beträgt
1.26; bei Zahlung während der alten X402-Zahlungsrabattrichtlinie betrug der tatsächlich signierte und abgerechnete Betrag1.2USDC, entsprechend1200000Atomic-USDC.
resource hier ein vom Server zurückgegebenes und an der Signatur beteiligtes Feld ist; der Client darf das darin enthaltene Protokoll, den Pfad oder die Bestell-ID nicht selbst ändern.
Signieren und erneut versuchen
Für die Bestellzahlung können die Low-Level-Signaturfunktionen von@acedatacloud/x402-client oder acedatacloud-x402 wiederverwendet werden. Nachfolgend ein TypeScript-Beispiel:
exact:
status 200zeigt an, dass die Zahlungs-API der Plattform diesePAYMENT-SIGNATUREakzeptiert hat.has_x_payment_response Truezeigt an, dass der Antwort-Header den Base64-kodiertenPAYMENT-RESPONSE-Beleg enthält.settle_header.success=Trueundnetwork=basezeigen an, dass der Facilitator das Base-Settlement abgeschlossen hat.- Der endgültige Bestellstatus ist
Finished,pay_wayistX402, undpay_identhält den On-Chain-Transaktions-Hash. - Das
Transfer-Ereignis auf BaseScan zeigt, dass die Zahlungsadresse1200000atomic USDC, also1.2USDC, an die Empfangsadresse der Plattform überwiesen hat.
Erfolgreiche Antwort und Beleg
Nach erfolgreicher Bestellzahlung enthält der Antworttext die Bestellinformationen. Die Plattform führt außerdem im Antwort-HeaderPAYMENT-RESPONSE die Base64-kodierte Settlement-Antwort mit, deren häufige Felder nach der Dekodierung Folgendes umfassen:
Wenn Sie eine Abstimmung benötigen, wird empfohlen, gleichzeitig die Bestell-ID, die Wallet-Adresse des Zahlers,
transaction und den endgültigen Bestellstatus zu speichern.
Hinweise
- Die Bestellzahlung benötigt ein Plattformkonto-Token und kann nicht allein mit einer X402-Wallet-Signatur abgeschlossen werden.
amountverwendet USDC atomic units,1200000steht für1.2USDC.- Setzen Sie Empfangs- oder Asset-Adressen nicht selbst zusammen; maßgeblich sind die
acceptsin der 402-Antwort. - Wenn dieselbe
PAYMENT-SIGNATUREwiederholt übermittelt wird, führt der Facilitator anhand des Nonce einen Replay-Schutz durch.
Antwort bei Zahlungsfehler
Die erste HTTP 402 ohnePAYMENT-SIGNATURE ist eine normale Zahlungsaufforderung und bedeutet keinen Zahlungsfehler. Bei einem Fehler bei der signierten Verifizierung oder beim Settlement bleibt der standardmäßige String error als kompatibler Fallback erhalten, und unter extensions.acedatacloud.paymentError wird eine stabile Fehlerstruktur zurückgegeben:
code lokalisieren; unbekannte Codes fallen auf einen allgemeinen Zahlungsfehler zurück. charged ist ein dreistufiges Feld: Nur bei einer eindeutigen Ablehnung vor dem Settlement wird false zurückgegeben; ein fehlendes Feld bedeutet, dass der Abbuchungsstatus unbekannt ist, und darf nicht als „nicht abgebucht“ interpretiert werden. Nachdem die aktuelle Bestellung in Failed übergegangen ist, kann sie nicht als dieselbe Bestellung erneut versucht werden; erstellen Sie nach der Behebung des Wallet-Problems eine neue Bestellung.
metadata.x402.last_error und metadata.x402.errors in der Bestellliste und den Bestelldetails behalten dieselbe Gruppe aus code, stage, retryable, charged und params; der öffentliche Beschreibungstext wird in reason gespeichert, und der Zeitpunkt des Auftretens wird in timestamp gespeichert. Beispielsweise bedeutet insufficient_token_balance, dass das USDC-Guthaben im ausgewählten Netzwerk nicht ausreicht, und invalid_signature bedeutet, dass die Zahlungssignatur ungültig ist; ein erneutes Abrufen der Bestellung ändert sie nicht in das allgemeine payment_failed.
Protokollieren oder übermitteln Sie nicht die vollständige PAYMENT-SIGNATURE, Wallet-Signaturen, Autorisierungs-Payloads, ursprüngliche Facilitator-Diagnosen oder RPC-Antworten. Für die Support-Fehlersuche werden nur die Bestell-ID und der öffentliche Fehler-code benötigt.
ACE-Rückkauf und -Verbrennung für Base- und Solana-Zahlungen
Nach Aktivierung der Rückkaufstrategie werden 3 % der tatsächlich eingegangenen Beträge von qualifiziertem Circle USDC im Base-Mainnet und USDC im Solana-Mainnet zum Kauf und zur Verbrennung von ACE verwendet, ohne der Wallet des Zahlers zusätzlich etwas zu berechnen. Die Rückstellung erfolgt einmal bei der Aufladung; bei der späteren Nutzung dieser Credits zum Aufrufen der API erfolgt keine wiederholte Rückstellung; historische rabattierte Bestellungen und Bestellungen mit alten Strategien werden nicht automatisch rückwirkend berücksichtigt. Base-Zahlungen behalten den Zahlungsbeleg auf der Base-Chain, während der Kauf und die Verbrennung von ACE asynchron auf Solana ausgeführt werden. Für qualifizierte Zahlungen werden exakt 3 % des tatsächlich eingegangenen Betrags zurückgestellt, ohne feste Obergrenze für Rückkäufe pro Einzeltransaktion oder pro Tag; verfügbare Mittel, Marktpreise und On-Chain-Bestätigungen können dennoch die Abschlusszeit beeinflussen. Das Objektace_burn in den Bestelldetails stellt settlement_network, settlement_transaction und execution_network bereit und stellt nach Abschluss swap_signature und burn_signature bereit. Pending oder Processing bedeutet nicht, dass bereits verbrannt wurde; nur Completed steht dafür, dass der endgültige On-Chain-Nachweis überprüft wurde. Wenn eine Base-Zahlung noch keine endgültige Bestätigung erreicht hat, wartet der Rückkauf auf die Bestätigung, ohne die bereits eingegangenen Credits zu beeinträchtigen.
