Controllare l’ingresso pubblico
Dichiarazione delle capacità del Facilitator:facilitator, supportedKinds e gli endpoint del protocollo, i metadati delle capacità sono normali. La scoperta delle risorse API è stata ritirata; chiamare direttamente l’API di destinazione e fare riferimento alla risposta 402 in tempo reale.
Capacità supportate dal Facilitator:
kinds, l’ingresso del Facilitator è normale.
Controllare accepts di 402
Inviare una richiesta non autenticata che non comporta addebiti:
accepts nella risposta contiene la rete che si desidera utilizzare. network è un identificatore CAIP-2:
eip155:8453+exact(Base)eip155:8453+upto(Base, misurazione post-utilizzo)solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp+exact(Solana)
Eseguire gli strumenti di verifica avanzata di X402Client
Il repository X402Client fornisce strumenti di verifica avanzata, utilizzabili per confermare la selezione della risposta 402, la generazione della firma, il paid retry e il settlement on-chain. Richiedono funded wallet, RPC, chiavi private e dipendenze di sviluppo. Per le normali integrazioni aziendali, si consiglia di utilizzare prioritariamente l’SDK TypeScript o Python; eseguire questi strumenti solo quando è necessario individuare problemi di firma o settlement on-chain. Indirizzo del repository: https://github.com/AceDataCloud/X402Client- La risposta 402 della prima richiesta.
- Il payment requirement selezionato.
- Il riepilogo del
PAYMENT-SIGNATUREdopo la firma. - Lo stato HTTP e il corpo della risposta dopo il retry.
- La settlement transaction on-chain, oppure il motivo dell’errore del Facilitator in caso di fallimento.
PAYMENT-SIGNATURE completi ai sistemi di log o nei ticket.
Esempio di risultati di verifica dell’API pubblica:
- Base
exact, Solanaexacte Baseuptohanno tutti completato il paid retry da HTTP 402 a HTTP 200. - La transazione on-chain di Base
exactè consultabile su BaseScan e l’importo del settlement è95215atomic USDC. - Il limite firmato di Base
uptoè95215atomic USDC, ma il settlement on-chain effettivo è3atomic USDC, indicando che la misurazione post-utilizzo addebita in base all’utilizzo reale. - Il percorso Solana ha confermato il paid retry e l’output del modello. L’RPC pubblico potrebbe essere soggetto a rate limit; quando è necessaria una rigorosa riconciliazione on-chain, utilizzare il proprio RPC Solana o i record di settlement lato piattaforma per confermare la firma della transazione.
SDK smoke test
Gli strumenti di verifica avanzata vengono utilizzati per controllare firme e settlement on-chain. Il lato aziendale deve inoltre eseguire uno SDK smoke test per confermare che il codice dell’applicazione possa gestire automaticamente il 402 tramite il payment handler. Di seguito vengono mostrati solo i frammenti principali; il codice completo deve integrare wallet, provider e import. TypeScript:exact e regolano l’importo fisso quotato dal 402. Il completamento della chat è uno scenario misurato in base ai token; nell’integrazione formale si consiglia di passare preferScheme: 'upto' (in Python prefer_scheme="upto"), per regolare in base all’utilizzo reale.
L’oggetto restituito dall’SDK Python è un dict; è possibile utilizzare res["choices"][0]["message"]["content"] per leggere il contenuto.
E2E del pagamento dell’ordine
Il pagamento dell’ordine utilizza l’API della piattaforma diplatform.acedata.cloud e richiede un token dell’account della piattaforma. Il flusso completo è: creare un ordine Pending, POST /api/v1/orders/{order_id}/pay/ attiva il 402, quindi eseguire un retry con PAYMENT-SIGNATURE.
Esempio di risultati di verifica per il pagamento di un piccolo ordine:
I seguenti record di transazione sono campioni di test storici secondo la vecchia politica; gli importi e gli hash delle transazioni sono mantenuti invariati. I nuovi ordini X402 non offrono più sconti sul metodo di pagamento; utilizzare l’amount nella risposta 402 corrente come base per la firma e il pagamento.
- Dopo la creazione dell’ordine, lo stato dell’ordine è
Pendinge il prezzo è1.26. - La prima richiesta
pay/restituisce HTTP 402; inacceptssono presenti Baseexacte Solanaexact, con importi entrambi pari a1200000atomic USDC. - Dopo aver riprovato con la
PAYMENT-SIGNATUREdi Base, viene restituito HTTP 200, lo stato dell’ordine diventaFinishedepay_wayèX402. - Dopo la decodifica di
PAYMENT-RESPONSE, vengono mostratisuccess=True,network=basee lo stesso hash della transazione. - Su BaseScan, lo stato della transazione è
1, l’importo del trasferimento è1200000atomic USDC, ovvero1.2USDC. - Il prezzo di creazione
1.26è stato pagato durante il periodo della vecchia politica di sconto dei pagamenti X402; l’importo finale della firma e del regolamento è1.2USDC.
Authorization: Bearer {platform_token}, oppure se l’ordine non appartiene all’account corrente, fallirà al livello dei permessi della piattaforma; questo è diverso dall’API X402 senza account chiamata direttamente su x402.acedata.cloud.
Errori comuni
Checklist di controllo Base upto
upto è attualmente disponibile solo su Base (eip155:8453). Poiché la firma upto vincola più parametri EVM typed data, durante l’integrazione occorre confermare in particolare che i campi in tempo reale della risposta 402 coincidano completamente con la firma del client.
upto restituisce invalid_upto_evm_payload_invalid_signature, controllare prioritariamente:
extra.chainId(deve essere8453) nell’elementoeip155:8453+uptorestituito dall’API.extra.facilitatorAddressrestituito dall’API.- L’indirizzo del facilitator Base
uptorestituito dahttps://facilitator.acedata.cloud/supported. - Il dominio Permit2, spender, contratto USDC e account di firma.
- Se il wallet ha già approvato Permit2 per Base USDC.
upto vincola contemporaneamente il dominio Permit2, chain ID, spender, indirizzo del destinatario, indirizzo del facilitator e validAfter. Se uno qualsiasi di essi non coincide, il Facilitator recupererà un signer errato, restituendo quindi invalid signature. Se tutti coincidono ma viene comunque restituito 402, controllare successivamente la allowance Permit2; in assenza di autorizzazione viene restituito PERMIT2_ALLOWANCE_REQUIRED.
Salvare le informazioni di verifica
Per una verifica completa, salvare almeno:- Il path API e il riepilogo del corpo della richiesta;
- Il network e lo scheme selezionati;
maxAmountRequired;- L’indirizzo del wallet payer;
- Lo stato HTTP finale;
- L’output del modello o l’ID del task nella risposta;
- Il link della transazione di settlement;
- Il Gateway trace ID o l’ID del record di utilizzo della piattaforma.
PAYMENT-SIGNATURE completa, signature EIP-712 completa o frase mnemonica.
Errori di pagamento strutturati
I fallimenti X402 dopo la firma restituiscono inextensions.acedatacloud.paymentError un code stabile, parametri di interpolazione sicuri, fase e indicatore di ripetibilità. Per la diagnosi, usare prioritariamente questa struttura; non analizzare l’error inglese di primo livello e non richiedere agli utenti la firma del wallet o il testo originale della simulazione on-chain.
charged: false: la verifica è stata esplicitamente rifiutata prima del settlement; in questa occasione non è stato avviato alcun addebito.- Senza
charged: il risultato è sconosciuto oppure è già entrato nella fase di settlement; controllare prima l’ordine e lo stato on-chain, ed è vietato ripetere direttamente il pagamento. settlement_pending: non ripetere per ora il pagamento; aggiornare prima l’ordine o contattare il supporto.- Code non riconosciuto: trattare come
payment_failede conservare il codice tecnico pubblico per la ricerca da parte del servizio clienti.

