Hoppa till huvudinnehåll
Utöver att betala direkt per API-begäran stöder Ace Data Cloud även betalning av konsolordrar med X402. Kärnprotokollet för orderbetalning och API-anrop är detsamma: den första begäran returnerar 402, klienten signerar PAYMENT-SIGNATURE och försöker sedan igen med samma begäran. Skillnaden är att orderbetalning tillhör plattformens API och kräver en kontotoken; medan direktanrop till AI API:t på x402.acedata.cloud endast kan använda X402 och inte kräver en API Token.

Förbered ordern

Gå till Ace Data Cloud-konsolen, välj ordern som ska betalas och anteckna order-ID:t. Om du ännu inte har någon order kan du skapa en obetald order på paketsidan. Orderpriset baseras på vad som visas på sidan, och amount i X402 402-svaret är den slutliga grunden för signering.

Skapa kontotoken

Begäran om orderbetalning kräver en kontotoken. Öppna plattformens Token-sida och skapa en token i formatet platform-v1-.... Använd följande i efterföljande begäranden:
Kontotoken skiljer sig från vanlig API Token. Vanlig API Token används för att förbruka API-kvot; kontotoken används för att representera ditt konto vid hantering av plattformsresurser, exempelvis orderbetalning.

Utlös 402

Skicka först en begäran utan PAYMENT-SIGNATURE:
Returneringsstatusen är 402, och svaret innehåller accepts:
Orderbetalning använder officiella x402 v2: x402Version är 2, network använder CAIP-2-identifierare och beloppsfältet är amount. Programkörningsresultat för att skapa en order på 10 Credits och utlösa 402:
Följande transaktionsposter är historiska testexempel under den gamla policyn, och belopp samt transaktionshashar behålls oförändrade. Nya X402-ordrar har inte längre rabatt för betalningsmetod; använd amount i det aktuella 402-svaret som grund för signering och betalning.
Resultatförklaring:
  • Efter att ordern har skapats är statusen Pending, och det finns ännu ingen betalning på kedjan.
  • Den första pay/-begäran innehåller inte PAYMENT-SIGNATURE, så den returnerar HTTP 402.
  • accepts anger samtidigt Base exact och Solana exact; i den fortsatta delen av denna handledning väljs Base.
  • Priset när ordern skapades var 1.26; vid betalning under den gamla rabattpolicyn för X402-betalning var det faktiska signerade och avräknade beloppet 1.2 USDC, motsvarande 1200000 atomic USDC.
Observera att resource här är ett fält som returneras av servern och deltar i signeringen, och klienten ska inte själv ändra protokollet, sökvägen eller order-ID:t i det.

Signera och försök igen

Orderbetalning kan återanvända lågnivåsigneringsfunktionerna i @acedatacloud/x402-client eller acedatacloud-x402. Nedan följer ett TypeScript-exempel:
Programkörningsresultat efter att samma order signerats med Base exact och försökt igen:
Resultat för bekräftelse på kedjan:
Resultatförklaring:
  • status 200 innebär att plattformens betalningsgränssnitt för beställningar accepterade denna PAYMENT-SIGNATURE.
  • has_x_payment_response True innebär att svarshuvudet innehåller det Base64-kodade kvittot PAYMENT-RESPONSE.
  • settle_header.success=True och network=base innebär att Facilitator har slutfört Base settlement.
  • Beställningens slutliga status är Finished, pay_way är X402 och pay_id skrivs med transaktionshashet på kedjan.
  • Händelsen Transfer på BaseScan visar att betalningsadressen överförde 1200000 atomic USDC till plattformens mottagaradress, det vill säga 1.2 USDC.

Lyckat svar och kvitto

Efter att beställningsbetalningen har lyckats är svarskroppen beställningsinformation. Plattformen inkluderar även ett Base64-kodat settlement-svar i svarshuvudet PAYMENT-RESPONSE; efter avkodning omfattar vanliga fält: Om du behöver stämma av rekommenderas att samtidigt spara beställnings-ID, betalande plånboksadress, transaction och beställningens slutliga status.

Observera

  • Beställningsbetalning kräver en plattformskontotoken och kan inte slutföras enbart med en X402-plånbokssignatur.
  • amount använder USDC atomic units; 1200000 innebär 1.2 USDC.
  • Sätt inte själv ihop mottagaradressen eller tillgångsadressen; utgå från accepts i 402-svaret.
  • Om samma PAYMENT-SIGNATURE skickas in upprepade gånger använder Facilitator nonce för skydd mot återuppspelning.

Svar vid betalningsfel

Den första HTTP 402 utan PAYMENT-SIGNATURE är en normal betalningsutmaning och innebär inte att betalningen misslyckades. Verifierings- eller avvecklingsfel efter signering behåller fortfarande standardsträngen error som kompatibilitetsreserv och returnerar en stabil felstruktur i extensions.acedatacloud.paymentError:
Klienten bör i första hand lokalisera efter code; okända code ska falla tillbaka till ett generellt betalningsfel. charged är ett trelägesfält: endast när betalningen uttryckligen nekas före avveckling returneras false; om fältet saknas är debiteringsstatusen okänd och får inte tolkas som ”inte debiterad”. När den aktuella beställningen har gått in i Failed kan den inte försökas igen med samma beställning; skapa en ny beställning efter att ha korrigerat plånboksproblemet. metadata.x402.last_error och metadata.x402.errors i beställningslistan och beställningsdetaljerna behåller samma uppsättning av code, stage, retryable, charged och params; offentlig beskrivningstext sparas i reason och tidpunkten för händelsen sparas i timestamp. Till exempel innebär insufficient_token_balance att USDC-saldot på det valda nätverket är otillräckligt, och invalid_signature innebär att betalningssignaturen är ogiltig; att läsa beställningen på nytt ändrar inte dessa till det generella payment_failed. Logga eller skicka inte in fullständig PAYMENT-SIGNATURE, plånbokssignaturer, auktoriserings-payloads, Facilitators ursprungliga diagnostik eller RPC-svar. Kundtjänstens felsökning behöver endast beställnings-ID och den offentliga felkoden code.

ACE-återköp och bränning för Base- och Solana-betalningar

Efter att återköpsstrategin har aktiverats används 3 % av det mottagna beloppet från kvalificerade Circle USDC på Base huvudnät och USDC på Solana huvudnät för att köpa och bränna ACE, utan någon extra debitering från den betalande plånboken. En avsättning görs en gång vid påfyllning; efterföljande API-anrop med dessa Credits medför inte ytterligare avsättning; historiska rabattbeställningar och beställningar med gamla strategier får inte automatiskt retroaktiv avsättning. Base-betalningar behåller betalningskvittot på Base-kedjan, medan köp och bränning av ACE utförs asynkront på Solana. Kvalificerade betalningar avsätts exakt med 3 % av det mottagna beloppet, utan fast gräns per transaktion eller dag för återköpsbelopp; tillgängliga medel, marknadskurser och bekräftelser på kedjan kan fortfarande påverka slutförandetiden. Objektet ace_burn i beställningsdetaljerna tillhandahåller settlement_network, settlement_transaction och execution_network, och tillhandahåller efter slutförande swap_signature och burn_signature. Pending eller Processing innebär inte att bränning redan har utförts; endast Completed representerar att det slutliga beviset på kedjan har kontrollerats. När en Base-betalning ännu inte har nått slutlig bekräftelse väntar återköpet på bekräftelse, men det påverkar inte redan mottagna Credits.