AceDataCloud x402 Guida all'integrazione dei pagamenti

• Documentazione panoramica su x402: https://docs.cdp.coinbase.com/x402/docs/overview
• Esempi open source di x402: https://github.com/coinbase/x402

• Il collegamento di pagamento avviene sulla rete principale Base, gli asset utilizzano USDC;
• È necessario utilizzare la chiave privata EVM del wallet per generare l’intestazione di firma X-PAYMENT;
• Tutte le API si trovano sotto il dominio https://platform.acedata.cloud, l’intestazione Authorization deve contenere il Platform Token.

​

I. Preparativi

​

1. Controlla l’ordine e registra le informazioni di pagamento

• ID ordine (ad esempio 7744945e-5e77-4dcc-a9c4-528692d17b34);
• Indirizzo di pagamento pay_to (restituito anche nella risposta 402, si consiglia di fare riferimento alle informazioni della pagina).

​

2. Prepara il wallet di pagamento e i fondi

• Prepara un wallet EVM che supporti la rete principale Base e esporta la chiave privata da utilizzare;
• Ricarica sufficienti USDC sulla rete principale Base (l’importo del pagamento è espresso in unità minime con 6 decimali);
• x402 Facilitator coprirà le spese di rete, il wallet di pagamento deve solo mantenere un numero sufficiente di USDC;
• La chiave privata è utilizzata solo per la firma locale, si prega di conservarla in modo sicuro, evitando di esporla nel browser o in ambienti non sicuri.

​

3. Crea il Platform Token

1. Apri la pagina della console https://platform.acedata.cloud/console/platform-tokens;
2. Clicca su “Crea Token”, compila le informazioni richieste e genera;
3. Copia il Token generato (ad esempio platform-v1-xxxx) e conservalo come platform_token.

Authorization: Bearer {platform_token}

​

4. Richiedi informazioni di base

• Dominio base API: https://platform.acedata.cloud
• Percorso della richiesta di pagamento: /api/v1/orders/{order_id}/pay/
• Richiesta e risposta utilizzano JSON, codificato in UTF-8.

​

II. Panoramica del processo di pagamento

1. Inizia la richiesta di pagamento: prima richiesta POST senza intestazione X-PAYMENT, attiva la piattaforma per restituire 402 Payment Required;
2. Leggi i requisiti di pagamento: analizza l’array accepts nella risposta 402, conferma che network sia base, asset sia USDC e payTo corrisponda a quanto indicato nella pagina dell’ordine;
3. Genera X-PAYMENT: utilizza la chiave privata del wallet di pagamento, i requisiti nel corpo della risposta, le informazioni del dominio EIP-712 restituite dal Facilitator per generare la firma (solitamente completata con l’SDK ufficiale);
4. Ritenta con la firma: aggiungi l’intestazione X-PAYMENT alla richiesta sullo stesso percorso, la piattaforma verifica e restituisce 200 se ha successo;
5. Analizza il risultato: leggi l’intestazione di risposta X-PAYMENT-RESPONSE, puoi ottenere l’hash della transazione on-chain, l’importo effettivamente addebitato e altre informazioni per la riconciliazione.

​

III. Esempi di integrazione

​

1. Prima richiesta (attiva 402)

POST https://platform.acedata.cloud/api/v1/orders/{order_id}/pay/
Authorization: Bearer {platform_token}
Content-Type: application/json

{
  "pay_way": "X402"
}

{
  "error": "Pagamento richiesto per questo ordine.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54b268aa0e",
      "maxAmountRequired": "1250000",
      "payTo": "0x302afdd980aaefca3afa8df7222a6002774f6724",
      "extra": {
        "eip712": { "...": "..." }
      }
    }
  ],
  "paywall": { ... }
}

• network: deve essere base (rete principale Base);
• asset: indirizzo del contratto USDC su Base (esempio del contratto ufficiale sulla rete principale);
• maxAmountRequired: unità atomica di USDC necessaria per questo pagamento (1 USDC = 1.000.000 unità atomiche);
• payTo: indirizzo di pagamento della piattaforma, deve corrispondere a quanto indicato nella pagina dei dettagli dell’ordine;
• extra: informazioni del dominio EIP-712 necessarie per la firma, ecc.

​

2. Genera X-PAYMENT

1. Converti la chiave privata del wallet di pagamento in un oggetto account;
2. Registra i dati accepts dalla risposta 402, scegli l’opzione di pagamento con network == "base";
3. Chiama la funzione di firma fornita dall’SDK per generare la stringa X-PAYMENT codificata in Base64 (non è necessario collegarsi direttamente al facilitator dal client; il backend della piattaforma si occuperà di chiamare il facilitator per completare la verifica/risoluzione);
4. Si consiglia di verificare se maxAmountRequired è entro il limite accettabile, in caso contrario avvisare l’utente di ricaricare.

​

3. Ritenta con la firma

POST https://platform.acedata.cloud/api/v1/orders/{order_id}/pay/
Authorization: Bearer {platform_token}
Content-Type: application/json
X-PAYMENT: {base64_signed_payload}

{
  "pay_way": "X402"
}

X-PAYMENT-RESPONSE: eyJ0cmFuc2FjdGlvbiI6IjB4...==

​

IV. Esempi di codice multilingue

• ACE_PLATFORM_TOKEN：Token della piattaforma；
• ACE_X402_ORDER_ID：ID dell’ordine；
• ACE_X402_PRIVATE_KEY：Chiave privata del portafoglio di pagamento (con prefisso 0x)。

​

1. Axios（TypeScript）

import axios from "axios";
import { Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { buildPaymentHeader, decodePaymentResponse } from "x402-js";

const baseURL = "https://platform.acedata.cloud";
const orderId = process.env.ACE_X402_ORDER_ID!;
const platformToken = process.env.ACE_PLATFORM_TOKEN!;
const privateKey = process.env.ACE_X402_PRIVATE_KEY as Hex;

const account = privateKeyToAccount(privateKey);
const api = axios.create({
  baseURL,
  headers: {
    Authorization: `Bearer ${platformToken}`,
    "Content-Type": "application/json",
  },
});

async function payOrder() {
  const payPath = `/api/v1/orders/${orderId}/pay/`;

  const initial = await api.post(
    payPath,
    { pay_way: "X402" },
    { validateStatus: () => true }
  );
  if (initial.status !== 402) {
    throw new Error(`stato inaspettato ${initial.status}`);
  }

  const requirement = initial.data.accepts.find(
    (item: any) => item.network === "base"
  );
  if (!requirement) {
    throw new Error("nessun requisito base restituito");
  }

  const paymentHeader = await buildPaymentHeader({
    account,
    requirement,
  });

  const final = await api.post(
    payPath,
    { pay_way: "X402" },
    { headers: { "X-PAYMENT": paymentHeader } }
  );

  if (final.status >= 400) {
    throw new Error(`pagamento x402 fallito: ${final.status} ${final.statusText}`);
  }
  const receipt = decodePaymentResponse(final.headers["x-payment-response"]);
  console.log("ricevuta x402", receipt);
}

payOrder().catch(console.error);

​

2. Fetch（JavaScript）

import { wrapFetchWithPayment, decodePaymentResponse } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.ACE_X402_PRIVATE_KEY!);
const platformToken = process.env.ACE_PLATFORM_TOKEN!;
const orderId = process.env.ACE_X402_ORDER_ID!;
const fetchWithPayment = wrapFetchWithPayment(fetch, account);

async function payOrder() {
  const url = `https://platform.acedata.cloud/api/v1/orders/${orderId}/pay/`;

  const response = await fetchWithPayment(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${platformToken}`,
    },
    body: JSON.stringify({ pay_way: "X402" }),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`pagamento x402 fallito: ${response.status} ${errorBody}`);
  }

  const receipt = decodePaymentResponse(
    response.headers.get("x-payment-response")!
  );
  console.log("ricevuta x402", receipt);
}

payOrder().catch(console.error);

​

3. Python requests

import os
from eth_account import Account
from x402.clients.requests import x402_requests
from x402.clients.base import decode_x_payment_response

order_id = os.environ["ACE_X402_ORDER_ID"]
platform_token = os.environ["ACE_PLATFORM_TOKEN"]
account = Account.from_key(os.environ["ACE_X402_PRIVATE_KEY"])

session = x402_requests(
    account,
    payment_requirements_selector=lambda accepts, **_: next(
        req for req in accepts if req.network == "base" and req.scheme == "exact"
    ),
)

response = session.post(
    f"https://platform.acedata.cloud/api/v1/orders/{order_id}/pay/",
    json={"pay_way": "X402"},
    headers={"Authorization": f"Bearer {platform_token}"},
)

response.raise_for_status()
receipt_header = response.headers.get("X-PAYMENT-RESPONSE")
if receipt_header:
    print("ricevuta x402:", decode_x_payment_response(receipt_header))

​

4. Python httpx（异步）

import asyncio
import os
from eth_account import Account
from x402.clients.httpx import x402HttpxClient
from x402.clients.base import decode_x_payment_response

async def pay_order() -> None:
    order_id = os.environ["ACE_X402_ORDER_ID"]
    platform_token = os.environ["ACE_PLATFORM_TOKEN"]
    account = Account.from_key(os.environ["ACE_X402_PRIVATE_KEY"])

    async with x402HttpxClient(
        account=account,
        base_url="https://platform.acedata.cloud",
        headers={"Authorization": f"Bearer {platform_token}"},
        payment_requirements_selector=lambda accepts, **_: next(
            req for req in accepts if req.network == "base"
        ),
    ) as client:
        response = await client.post(
            f"/api/v1/orders/{order_id}/pay/",
            json={"pay_way": "X402"},
        )
        response.raise_for_status()
        receipt_header = response.headers.get("X-PAYMENT-RESPONSE")
        if receipt_header:
            print("ricevuta x402:", decode_x_payment_response(receipt_header))

asyncio.run(pay_order())

L’esempio mostra solo le chiamate chiave, in un ambiente di produzione si prega di aggiungere gestione delle eccezioni, strategie di ripetizione, registrazione e controllo della sicurezza.

​

Cinque, verifica dopo il pagamento riuscito

• Verifica della console：Visita la pagina dei dettagli dell’ordine https://platform.acedata.cloud/console/orders/{order_id}. Se la pagina mostra “Pagamento riuscito” o lo stato dell’ordine è cambiato in pagato/completato, significa che il regolamento sulla catena è completato.
• Verifica API：Chiama GET https://platform.acedata.cloud/api/v1/orders/{order_id}/ e porta Authorization: Bearer {platform_token}, controlla il campo state nella risposta ( PAID o FINISHED indica pagamento riuscito).
• Intestazione di ritorno：Leggi X-PAYMENT-RESPONSE nella risposta di pagamento riuscito, puoi decodificare l’hash della transazione sulla catena come prova finale; si consiglia di salvare queste informazioni nei registri di sistema per la riconciliazione.

​

Sei, risoluzione dei problemi comuni

• Restituisce ancora 402：Verifica che l’indirizzo di pagamento abbia abbastanza USDC sulla rete principale Base, controlla se maxAmountRequired supera il saldo del portafoglio o il limite personalizzato.
• Errore di firma：Assicurati che la chiave privata abbia il prefisso 0x; durante la firma utilizza rigorosamente extra (campo EIP-712) e payTo nella risposta, non modificare l’ordine dei campi.
• Rete non corrispondente：Potrebbero esserci più requisiti in accepts, seleziona l’opzione network === "base".
• Manca X-PAYMENT-RESPONSE：Indica che il pagamento non è stato effettivamente addebitato, puoi ripetere l’operazione in base all’errore nel corpo della risposta; se si verifica congestione sulla catena, riprova più tardi.
• Token della piattaforma non valido：Verifica che il token non sia stato eliminato e inizi con il prefisso platform-v1-; se l’interfaccia restituisce 401, puoi rigenerarlo nella console.

​

Sette, ulteriore aiuto

• Documentazione online e domande frequenti: navigazione in alto nella console della piattaforma “Documentazione”.
• Invia un ticket e supporto clienti: https://platform.acedata.cloud/support
• Comunicazione nella comunità: Discord https://discord.gg/f9GRuKCmRc, X (Twitter) https://x.com/acedatacloud
• Altri canali: email office@acedata.cloud, office@germey.tech; indirizzo aziendale 651 N Broad St, Suite 201, Middletown, Delaware, USA; per il supporto WeChat controlla il codice QR più recente nella pagina di supporto.
• Feedback e suggerimenti: ti invitiamo a farci sapere le tue esigenze di miglioramento attraverso uno dei canali sopra.