AceDataCloud x402 Zahlungsintegrationsleitfaden

• x402 Übersichtsdokument: https://docs.cdp.coinbase.com/x402/docs/overview
• x402 Open-Source-Beispiel: https://github.com/coinbase/x402

• Die Zahlungsabwicklung erfolgt im Base Mainnet, die Vermögenswerte verwenden USDC;
• Es muss der EVM Private Key der Wallet verwendet werden, um den X-PAYMENT Signatur-Header zu generieren;
• Alle APIs befinden sich unter der Domain https://platform.acedata.cloud, der Authorization Header muss das Platform Token enthalten.

​

I. Vorbereitungen

​

1. Bestellungen einsehen und Zahlungsinformationen aufzeichnen

• Bestell-ID (z. B. 7744945e-5e77-4dcc-a9c4-528692d17b34);
• Empfangsadresse pay_to (wird auch in der 402-Antwort zurückgegeben, es wird empfohlen, sich an die Seiteninformationen zu halten).

​

2. Zahlungsmittel und -mittel vorbereiten

• Bereite eine EVM-Wallet vor, die das Base Mainnet unterstützt, und exportiere den zu verwendenden Private Key;
• Lade ausreichend USDC (Zahlungsbetrag in der kleinsten Einheit mit 6 Dezimalstellen) auf das Base Mainnet;
• Der x402 Facilitator übernimmt die Netzwerkgebühren, die Zahlungsmittel-Wallet muss nur genügend USDC behalten;
• Der Private Key wird nur für lokale Signaturen verwendet, bitte bewahre ihn sicher auf und vermeide es, ihn im Browser oder in unsicheren Umgebungen offenzulegen.

​

3. Platform Token erstellen

1. Öffne die Dashboard-Seite https://platform.acedata.cloud/console/platform-tokens;
2. Klicke auf „Token erstellen“, fülle die Hinweisinformationen gemäß den Anweisungen aus und generiere es;
3. Kopiere das generierte Token (z. B. platform-v1-xxxx) und bewahre es sicher als platform_token auf.

Authorization: Bearer {platform_token}

​

4. Grundlegende Informationen anfordern

• API Basis-Domain: https://platform.acedata.cloud
• Zahlungsanforderungspfad: /api/v1/orders/{order_id}/pay/
• Anfragen und Antworten verwenden JSON, kodiert in UTF-8.

​

II. Übersicht des Zahlungsprozesses

1. Zahlungsanforderung initiieren: Erste POST-Anfrage ohne X-PAYMENT-Header, die die Plattform dazu bringt, 402 Payment Required zurückzugeben;
2. Zahlungsanforderungen lesen: Analysiere das accepts-Array in der 402-Antwort, um sicherzustellen, dass network auf base, asset auf USDC und payTo mit der Bestellseite übereinstimmt;
3. X-PAYMENT generieren: Verwende den Private Key der Zahlungsmittel-Wallet, die Anforderungen im Antwortkörper, die von Facilitator zurückgegebenen EIP-712-Daten usw., um die Signatur zu generieren (normalerweise mithilfe des offiziellen SDK);
4. Mit Signatur erneut versuchen: Füge den X-PAYMENT-Header zur Anfrage am gleichen Pfad hinzu, die Plattform validiert und gibt bei Erfolg 200 zurück;
5. Ergebnisse analysieren: Lese den Antwort-Header X-PAYMENT-RESPONSE, um die On-Chain-Transaktionshash, den tatsächlich abgebuchten Betrag und andere Informationen für die Abrechnung zu erhalten.

​

III. Integrationsbeispiele

​

1. Erste Anfrage (Auslösen von 402)

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

{
  "pay_way": "X402"
}

{
  "error": "Zahlung für diese Bestellung erforderlich.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54b268aa0e",
      "maxAmountRequired": "1250000",
      "payTo": "0x302afdd980aaefca3afa8df7222a6002774f6724",
      "extra": {
        "eip712": { "...": "..." }
      }
    }
  ],
  "paywall": { ... }
}

• network: muss base (Base Mainnet) sein;
• asset: Base USDC Vertragsadresse (Beispiel für den offiziellen Hauptnetzvertrag);
• maxAmountRequired: die für diese Zahlung erforderliche USDC-Atomareinheit (1 USDC = 1.000.000 atomare Einheiten);
• payTo: Plattform-Empfangsadresse, sollte mit der Bestelldetailseite übereinstimmen;
• extra: EIP-712-Dateninformationen, die für die Signatur benötigt werden.

​

2. X-PAYMENT generieren

1. Konvertiere den Private Key der Zahlungsmittel-Wallet in ein Kontoobjekt;
2. Notiere die accepts-Daten aus der 402-Antwort und wähle die Zahlungsoption mit network == "base";
3. Rufe die Signaturfunktion des SDK auf, um den Base64-kodierten X-PAYMENT-String zu generieren (keine direkte Verbindung des Clients zum Facilitator erforderlich; das Backend der Plattform kümmert sich um die Aufrufe des Facilitators zur Verifizierung/Abwicklung);
4. Es wird empfohlen, zu überprüfen, ob maxAmountRequired im akzeptablen Bereich liegt, andernfalls den Benutzer aufzufordern, Guthaben aufzuladen.

​

3. Mit Signatur erneut versuchen

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. Mehrsprachige Beispielcodes

• ACE_PLATFORM_TOKEN：Plattform-Token；
• ACE_X402_ORDER_ID：Bestell-ID；
• ACE_X402_PRIVATE_KEY：Zahlungs-Wallet-Privatschlüssel (mit 0x Präfix).

​

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(`unerwarteter Status ${initial.status}`);
  }

  const requirement = initial.data.accepts.find(
    (item: any) => item.network === "base"
  );
  if (!requirement) {
    throw new Error("keine Basisanforderung zurückgegeben");
  }

  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(`x402-Zahlung fehlgeschlagen: ${final.status} ${final.statusText}`);
  }
  const receipt = decodePaymentResponse(final.headers["x-payment-response"]);
  console.log("x402 Quittung", 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(`x402-Zahlung fehlgeschlagen: ${response.status} ${errorBody}`);
  }

  const receipt = decodePaymentResponse(
    response.headers.get("x-payment-response")!
  );
  console.log("x402 Quittung", 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("x402 Quittung:", decode_x_payment_response(receipt_header))

​

4. Python httpx (asynchron)

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("x402 Quittung:", decode_x_payment_response(receipt_header))

asyncio.run(pay_order())

Beispiel zeigt nur die wesentlichen Aufrufe, in der Produktionsumgebung bitte Fehlerbehandlung, Wiederholungsstrategien, Protokollierung und Sicherheitskontrollen ergänzen.

​

Fünf, Überprüfung nach erfolgreicher Zahlung

• Konsole Überprüfung: Besuchen Sie die Bestelldetailseite https://platform.acedata.cloud/console/orders/{order_id}, wenn die Seite „Zahlung erfolgreich“ anzeigt oder der Bestellstatus auf bezahlt/abgeschlossen geändert wurde, bedeutet dies, dass die On-Chain-Abwicklung abgeschlossen ist.
• API Überprüfung: Rufen Sie GET https://platform.acedata.cloud/api/v1/orders/{order_id}/ auf und fügen Sie Authorization: Bearer {platform_token} hinzu, überprüfen Sie das state-Feld in der Antwort ( PAID oder FINISHED bedeutet Zahlung erfolgreich).
• Rückgabe-Header: Lesen Sie im Antworttext der erfolgreichen Zahlung den X-PAYMENT-RESPONSE, um den On-Chain-Transaktionshash als endgültigen Beleg zu entschlüsseln; es wird empfohlen, diese Informationen im Systemprotokoll zu speichern, um die Abrechnung zu erleichtern.

​

Sechs, häufige Probleme und deren Lösung

• Gibt weiterhin 402 zurück: Stellen Sie sicher, dass die Zahlungsadresse im Base-Hauptnetz über genügend USDC verfügt, überprüfen Sie, ob maxAmountRequired das Wallet-Guthaben oder benutzerdefinierte Limits überschreitet.
• Signatur fehlgeschlagen: Stellen Sie sicher, dass der Privatschlüssel mit 0x Präfix versehen ist; verwenden Sie beim Signieren strikt die extra (EIP-712-Domain) und payTo aus der Antwort, ändern Sie nicht die Reihenfolge der Felder.
• Netzwerk stimmt nicht überein: In accepts können mehrere Anforderungen vorhanden sein, wählen Sie die Option network === "base".
• Fehlender X-PAYMENT-RESPONSE: Dies bedeutet, dass keine tatsächliche Zahlung abgebucht wurde, Sie können basierend auf dem Fehler im Antworttext erneut anfordern; bei On-Chain-Staus bitte später erneut versuchen.
• Plattform-Token ungültig: Stellen Sie sicher, dass das Token nicht gelöscht wurde und mit platform-v1- beginnt; wenn die Schnittstelle 401 zurückgibt, können Sie es im Dashboard neu generieren.

​

Sieben, weitere Hilfe

• Online-Dokumentation und häufige Fragen: Dokumente im oberen Navigationsbereich des Plattform-Dashboards.
• Ticket einreichen und Kundensupport: https://platform.acedata.cloud/support
• Community-Austausch: Discord https://discord.gg/f9GRuKCmRc, X (Twitter) https://x.com/acedatacloud
• Weitere Kanäle: E-Mail office@acedata.cloud, office@germey.tech; Firmenadresse 651 N Broad St, Suite 201, Middletown, Delaware, USA; WeChat-Kundendienst bitte auf der Support-Seite den neuesten QR-Code einsehen.
• Feedback und Vorschläge: Wir freuen uns über Ihre Verbesserungsvorschläge über einen der oben genannten Kanäle.