AceDataCloud x402 Платіжна інтеграція

• Оглядова документація x402: https://docs.cdp.coinbase.com/x402/docs/overview
• Відкритий приклад x402: https://github.com/coinbase/x402

• Платіжний ланцюг завершується в Base Mainnet, активи використовують USDC;
• Необхідно використовувати EVM приватний ключ гаманця для генерації заголовка підпису X-PAYMENT;
• Всі API розташовані на домені https://platform.acedata.cloud, заголовок Authorization повинен містити Platform Token.

​

I. Підготовчі роботи

​

1. Перегляд замовлення та запис інформації про отримання

• ID замовлення (наприклад, 7744945e-5e77-4dcc-a9c4-528692d17b34);
• Адреса отримання pay_to (також буде повернена в 402 відповіді, рекомендується орієнтуватися на інформацію зі сторінки).

​

2. Підготовка платіжного гаманця та коштів

• Підготуйте гаманець EVM, що підтримує Base Mainnet, та експортуйте приватний ключ, який буде використовуватися;
• Поповніть Base Mainnet достатньою кількістю USDC (сума платежу в одиницях з 6 знаками після коми);
• x402 Facilitator покриє мережеві витрати, платіжному гаманцю потрібно лише зберігати достатню кількість USDC;
• Приватний ключ використовується лише для локального підписання, будь ласка, зберігайте його в безпеці, уникаючи його розкриття в браузері або ненадійних середовищах.

​

3. Створення Platform Token

1. Відкрийте сторінку консолі https://platform.acedata.cloud/console/platform-tokens;
2. Натисніть «Створити токен», заповніть інформацію про примітки відповідно до підказок і згенеруйте;
3. Скопіюйте згенерований токен (наприклад, platform-v1-xxxx), зберігайте його як platform_token.

Authorization: Bearer {platform_token}

​

4. Запит базової інформації

• Базовий домен API: https://platform.acedata.cloud
• Шлях запиту на оплату: /api/v1/orders/{order_id}/pay/
• Запити та відповіді використовують JSON, кодування UTF-8.

​

II. Огляд процесу оплати

1. Ініціювати запит на оплату: перший POST запит без заголовка X-PAYMENT, що викликає повернення платформи 402 Payment Required;
2. Зчитати вимоги до оплати: розібрати масив accepts у відповіді 402, підтвердити, що network є base, asset є USDC, payTo відповідає даним на сторінці замовлення;
3. Генерувати X-PAYMENT: використовуючи приватний ключ платіжного гаманця, вимоги з тіла відповіді, інформацію EIP-712, повернуту Facilitator, згенерувати підпис (зазвичай за допомогою офіційного SDK);
4. Повторити запит з підписом: додати заголовок X-PAYMENT до запиту того ж шляху, після успішної перевірки платформа повертає 200;
5. Розібрати результати: зчитати заголовок відповіді X-PAYMENT-RESPONSE, щоб отримати хеш транзакції в ланцюгу, фактичну суму списання та іншу інформацію для звірки.

​

III. Приклад інтеграції

​

1. Перший запит (виклик 402)

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

{
  "pay_way": "X402"
}

{
  "error": "Payment required for this order.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54b268aa0e",
      "maxAmountRequired": "1250000",
      "payTo": "0x302afdd980aaefca3afa8df7222a6002774f6724",
      "extra": {
        "eip712": { "...": "..." }
      }
    }
  ],
  "paywall": { ... }
}

• network: має бути base (Base Mainnet);
• asset: адреса контракту Base USDC (приклад для офіційного контракту на основній мережі);
• maxAmountRequired: атомарна одиниця USDC, необхідна для цього платежу (1 USDC = 1,000,000 атомарних одиниць);
• payTo: адреса отримання платформи, повинна відповідати даним на сторінці деталей замовлення;
• extra: інформація EIP-712, необхідна для підпису тощо.

​

2. Генерація X-PAYMENT

1. Перетворити приватний ключ платіжного гаманця на об’єкт рахунку;
2. Записати дані accepts з відповіді 402, вибрати платіжний варіант з network == "base";
3. Викликати функцію підпису, надану SDK, для генерації рядка X-PAYMENT у форматі Base64 (не потрібно безпосередньо підключатися до facilitator; бекенд платформи відповідатиме за виклик facilitator для завершення перевірки/розрахунку);
4. Рекомендується перевірити, чи maxAmountRequired знаходиться в прийнятному діапазоні, якщо перевищує, попередити користувача про поповнення.

​

3. Повторний запит з підписом

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. Приклади коду на різних мовах

• ACE_PLATFORM_TOKEN：Токен платформи；
• ACE_X402_ORDER_ID：ID замовлення；
• ACE_X402_PRIVATE_KEY：Приватний ключ платіжного гаманця (з префіксом 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(`неочікуваний статус ${initial.status}`);
  }

  const requirement = initial.data.accepts.find(
    (item: any) => item.network === "base"
  );
  if (!requirement) {
    throw new Error("не повернуто базових вимог");
  }

  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 не вдався: ${final.status} ${final.statusText}`);
  }
  const receipt = decodePaymentResponse(final.headers["x-payment-response"]);
  console.log("квитанція 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(`платіж x402 не вдався: ${response.status} ${errorBody}`);
  }

  const receipt = decodePaymentResponse(
    response.headers.get("x-payment-response")!
  );
  console.log("квитанція 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("квитанція 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("квитанція x402:", decode_x_payment_response(receipt_header))

asyncio.run(pay_order())

Приклад лише демонструє ключові виклики, у виробничому середовищі будь ласка, додайте обробку винятків, стратегії повторних спроб, журнали та контроль безпеки.

​

П’ять, перевірка після успішної оплати

• Перевірка в консолі: відвідайте сторінку деталей замовлення https://platform.acedata.cloud/console/orders/{order_id}. Якщо на сторінці відображається «Оплата успішна» або статус замовлення змінився на оплачений/завершений, це означає, що розрахунок в ланцюгу завершено.
• Перевірка API: викличте GET https://platform.acedata.cloud/api/v1/orders/{order_id}/ і передайте Authorization: Bearer {platform_token}, перевірте поле state у відповіді (значення PAID або FINISHED означає успішну оплату).
• Заголовок відповіді: у відповіді на успішну оплату прочитайте X-PAYMENT-RESPONSE, з якого можна розшифрувати хеш транзакції в ланцюгу як остаточний доказ; рекомендується зберігати цю інформацію в системних журналах для звірки.

​

Шість, усунення поширених проблем

• Все ще повертає 402: підтвердіть, що платіжна адреса в основній мережі має достатньо USDC, перевірте, чи maxAmountRequired не перевищує баланс гаманця або власний ліміт.
• Помилка підпису: переконайтеся, що приватний ключ має префікс 0x; під час підпису строго використовуйте extra (EIP-712 поле) та payTo з відповіді, не змінюйте порядок полів.
• Несумісність мережі: у accepts може бути кілька вимог, виберіть опцію network === "base".
• Відсутній X-PAYMENT-RESPONSE: це означає, що платіж не був фактично списаний, можна повторно ініціювати на основі помилки в тілі відповіді; якщо виникає затримка в ланцюгу, будь ласка, спробуйте пізніше.
• Недійсний токен платформи: підтвердіть, що токен не був видалений і починається з префікса platform-v1-; якщо API повертає 401, можна знову згенерувати в консолі.

​

Сім, більше допомоги

• Онлайн-документація та поширені питання: верхнє меню консолі платформи «Документація».
• Подати запит та підтримка клієнтів: https://platform.acedata.cloud/support
• Спільнота: Discord https://discord.gg/f9GRuKCmRc, X (Twitter) https://x.com/acedatacloud
• Інші канали: електронна пошта office@acedata.cloud, office@germey.tech; адреса компанії 651 N Broad St, Suite 201, Middletown, Delaware, USA; для підтримки WeChat, будь ласка, перегляньте останній QR-код на сторінці підтримки.
• Відгуки та пропозиції: ми будемо раді дізнатися про ваші потреби в покращенні через будь-який з вищезазначених каналів.