AceDataCloud x402 Przewodnik po integracji płatności

• Dokumentacja przeglądowa x402: https://docs.cdp.coinbase.com/x402/docs/overview
• Przykład open source x402: https://github.com/coinbase/x402

• Płatność odbywa się w sieci głównej Base, a aktywa używają USDC;
• Należy użyć klucza prywatnego EVM portfela z aktywami do wygenerowania nagłówka podpisu X-PAYMENT;
• Wszystkie API znajdują się pod domeną https://platform.acedata.cloud, nagłówek Authorization musi zawierać Platform Token.

​

I. Przygotowania

​

1. Sprawdzenie zamówienia i zapisanie informacji o płatności

• ID zamówienia (np. 7744945e-5e77-4dcc-a9c4-528692d17b34);
• Adres płatności pay_to (zostanie również zwrócony w odpowiedzi 402, zaleca się opierać na informacjach ze strony).

​

2. Przygotowanie portfela płatniczego i funduszy

• Przygotuj portfel EVM obsługujący sieć główną Base i wyeksportuj klucz prywatny do użycia;
• Doładuj wystarczającą ilość USDC (kwota płatności w jednostkach o 6 miejscach po przecinku) w sieci głównej Base;
• x402 Facilitator pokryje koszty sieci, portfel płatniczy musi mieć tylko wystarczającą ilość USDC;
• Klucz prywatny jest używany tylko do lokalnego podpisywania, proszę go odpowiednio zabezpieczyć, aby uniknąć ujawnienia w przeglądarkach lub niepewnych środowiskach.

​

3. Utworzenie Platform Token

1. Otwórz stronę konsoli https://platform.acedata.cloud/console/platform-tokens;
2. Kliknij „Utwórz Token”, wypełnij informacje o uwagach zgodnie z instrukcjami, a następnie wygeneruj;
3. Skopiuj wygenerowany token (np. platform-v1-xxxx) i odpowiednio go przechowuj jako platform_token.

Authorization: Bearer {platform_token}

​

4. Żądanie podstawowych informacji

• Podstawowa domena API: https://platform.acedata.cloud
• Ścieżka żądania płatności: /api/v1/orders/{order_id}/pay/
• Żądania i odpowiedzi są w formacie JSON, kodowane jako UTF-8.

​

II. Przegląd procesu płatności

1. Inicjowanie żądania płatności: pierwsze żądanie POST bez nagłówka X-PAYMENT, które wyzwala platformę do zwrócenia 402 Payment Required;
2. Odczytanie wymagań płatności: analizowanie tablicy accepts w odpowiedzi 402, potwierdzenie, że network to base, asset to USDC, payTo jest zgodne z informacjami na stronie zamówienia;
3. Generowanie X-PAYMENT: użycie klucza prywatnego portfela płatniczego, wymagań z ciała odpowiedzi, informacji EIP-712 zwróconych przez Facilitatora do wygenerowania podpisu (zwykle przy pomocy oficjalnego SDK);
4. Ponowne wysłanie z podpisem: dodanie nagłówka X-PAYMENT do żądania na tej samej ścieżce, po pomyślnej weryfikacji platforma zwraca 200;
5. Analiza wyników: odczytanie nagłówka odpowiedzi X-PAYMENT-RESPONSE, można uzyskać hash transakcji on-chain, rzeczywistą kwotę obciążenia i inne informacje do rozliczeń.

​

III. Przykład integracji

​

1. Pierwsze żądanie (wyzwolenie 402)

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

{
  "pay_way": "X402"
}

{
  "error": "Płatność wymagana dla tego zamówienia.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54b268aa0e",
      "maxAmountRequired": "1250000",
      "payTo": "0x302afdd980aaefca3afa8df7222a6002774f6724",
      "extra": {
        "eip712": { "...": "..." }
      }
    }
  ],
  "paywall": { ... }
}

• network: musi być base (sieć główna Base);
• asset: adres kontraktu Base USDC (przykład to oficjalny kontrakt sieci głównej);
• maxAmountRequired: wymagana kwota USDC w jednostkach atomowych (1 USDC = 1,000,000 jednostek atomowych);
• payTo: adres płatności platformy, powinien być zgodny z informacjami na stronie szczegółów zamówienia;
• extra: informacje o polach EIP-712 wymagane do podpisu.

​

2. Generowanie X-PAYMENT

1. Przekształcenie klucza prywatnego portfela płatniczego w obiekt konta;
2. Zapisanie danych accepts z odpowiedzi 402, wybór opcji płatności, gdzie network == "base";
3. Wywołanie funkcji podpisu dostarczonej przez SDK w celu wygenerowania zakodowanego w Base64 ciągu X-PAYMENT (nie ma potrzeby bezpośredniego łączenia klienta z facilitatorem; backend platformy zajmie się wywołaniem facilitatora w celu weryfikacji/rozliczenia);
4. Zaleca się sprawdzenie, czy maxAmountRequired mieści się w akceptowalnym zakresie, w przeciwnym razie należy poinformować użytkownika o konieczności doładowania.

​

3. Ponowne wysłanie z podpisem

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. Przykładowy kod w wielu językach

• ACE_PLATFORM_TOKEN：Token platformy；
• ACE_X402_ORDER_ID：ID zamówienia；
• ACE_X402_PRIVATE_KEY：Prywatny klucz portfela płatności (z prefiksem 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(`nieoczekiwany status ${initial.status}`);
  }

  const requirement = initial.data.accepts.find(
    (item: any) => item.network === "base"
  );
  if (!requirement) {
    throw new Error("brak wymagań podstawowych");
  }

  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(`płatność x402 nie powiodła się: ${final.status} ${final.statusText}`);
  }
  const receipt = decodePaymentResponse(final.headers["x-payment-response"]);
  console.log("paragon 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(`płatność x402 nie powiodła się: ${response.status} ${errorBody}`);
  }

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

asyncio.run(pay_order())

Przykład pokazuje tylko kluczowe wywołania, w środowisku produkcyjnym należy dodać obsługę wyjątków, strategię ponawiania, logowanie i kontrolę bezpieczeństwa.

​

Pięć, weryfikacja po udanej płatności

• Weryfikacja w konsoli: Odwiedź stronę szczegółów zamówienia https://platform.acedata.cloud/console/orders/{order_id}, jeśli strona wyświetla „płatność zakończona” lub status zamówienia zmienił się na opłacone/zakończone, oznacza to, że rozliczenie na łańcuchu zostało zakończone.
• Weryfikacja API: Wywołaj GET https://platform.acedata.cloud/api/v1/orders/{order_id}/ z nagłówkiem Authorization: Bearer {platform_token}, sprawdź pole state w odpowiedzi ( PAID lub FINISHED oznacza, że płatność zakończona pomyślnie).
• Nagłówek zwrotny: W odpowiedzi po udanej płatności odczytaj X-PAYMENT-RESPONSE, można z niego wyodrębnić hash transakcji na łańcuchu jako ostateczny dowód; zaleca się zapisanie tej informacji w logach systemowych w celu rozliczenia.

​

Sześć, rozwiązywanie najczęstszych problemów

• Wciąż zwraca 402: Upewnij się, że adres płatności ma wystarczającą ilość USDC w sieci Base, sprawdź, czy maxAmountRequired nie przekracza salda portfela lub limitu niestandardowego.
• Błąd podpisu: Upewnij się, że prywatny klucz ma prefiks 0x; podczas podpisywania ściśle używaj extra (pole EIP-712) i payTo z odpowiedzi, nie zmieniaj kolejności pól.
• Niezgodność sieci: W accepts może być wiele wymagań, wybierz opcję network === "base".
• Brak X-PAYMENT-RESPONSE: Oznacza to, że płatność nie została faktycznie pobrana, można ponownie zainicjować na podstawie błędu w ciele odpowiedzi; w przypadku zatorów w sieci spróbuj ponownie później.
• Nieprawidłowy token platformy: Upewnij się, że token nie został usunięty i zaczyna się od prefiksu platform-v1-; jeśli interfejs zwraca 401, można ponownie wygenerować w konsoli.

​

Siedem, więcej pomocy

• Dokumentacja online i najczęściej zadawane pytania: nawigacja „Dokumentacja” na górze konsoli platformy.
• Zgłaszanie zgłoszeń i wsparcie klienta: https://platform.acedata.cloud/support
• Wspólna komunikacja: Discord https://discord.gg/f9GRuKCmRc, X (Twitter) https://x.com/acedatacloud
• Inne kanały: e-mail office@acedata.cloud, office@germey.tech; adres firmy 651 N Broad St, Suite 201, Middletown, Delaware, USA; obsługa WeChat, sprawdź najnowszy kod QR na stronie wsparcia.
• Opinie i sugestie: zachęcamy do informowania nas o potrzebach dotyczących ulepszeń za pośrednictwem dowolnego z powyższych kanałów.