AceDataCloud x402 Guia de Integração de Pagamento

• Documento de visão geral do x402: https://docs.cdp.coinbase.com/x402/docs/overview
• Exemplo de código aberto do x402: https://github.com/coinbase/x402

• O link de pagamento é concluído na rede principal Base, utilizando USDC como ativo;
• É necessário usar a chave privada EVM da carteira que possui os ativos para gerar o cabeçalho de assinatura X-PAYMENT;
• Todas as APIs estão localizadas sob o domínio https://platform.acedata.cloud, e o cabeçalho Authorization deve incluir o Token da Plataforma.

​

I. Preparativos

​

1. Verificar o pedido e registrar as informações de recebimento

• ID do pedido (por exemplo, 7744945e-5e77-4dcc-a9c4-528692d17b34);
• Endereço de recebimento pay_to (também será retornado na resposta 402, recomenda-se considerar as informações da página como referência).

​

2. Preparar a carteira de pagamento e os fundos

• Prepare uma carteira EVM que suporte a rede principal Base e exporte a chave privada a ser utilizada;
• Carregue a rede principal Base com a quantidade suficiente de USDC (o valor do pagamento deve ser em unidades mínimas com 6 casas decimais);
• O Facilitador x402 pagará as taxas de rede, a carteira de pagamento só precisa manter USDC suficiente;
• A chave privada é usada apenas para assinatura local, mantenha-a em segurança e evite expô-la em navegadores ou ambientes não confiáveis.

​

3. Criar Token da Plataforma

1. Abra a página do console https://platform.acedata.cloud/console/platform-tokens;
2. Clique em “Criar Token”, preencha as informações de anotação conforme solicitado e gere;
3. Copie o Token gerado (por exemplo, platform-v1-xxxx) e guarde-o como platform_token.

Authorization: Bearer {platform_token}

​

4. Solicitar informações básicas

• Domínio base da API: https://platform.acedata.cloud
• Caminho da solicitação de pagamento: /api/v1/orders/{order_id}/pay/
• Solicitações e respostas usam JSON, codificado em UTF-8.

​

II. Visão Geral do Fluxo de Pagamento

1. Iniciar solicitação de pagamento: primeira solicitação POST sem o cabeçalho X-PAYMENT, acionando a plataforma a retornar 402 Payment Required;
2. Ler requisitos de pagamento: analisar o array accepts na resposta 402, confirmando que network é base, asset é USDC, e payTo é consistente com a página do pedido;
3. Gerar X-PAYMENT: usar a chave privada da carteira de pagamento, os requisitos do corpo da resposta, e as informações do domínio EIP-712 retornadas pelo Facilitador para gerar a assinatura (geralmente com a ajuda do SDK oficial);
4. Repetir com a assinatura: adicionar o cabeçalho X-PAYMENT à solicitação do mesmo caminho, e a plataforma retornará 200 após a validação bem-sucedida;
5. Analisar resultados: ler o cabeçalho de resposta X-PAYMENT-RESPONSE, onde é possível obter o hash da transação em blockchain, o valor efetivamente debitado, entre outras informações para conciliação.

​

III. Exemplos de Integração

​

1. Primeira solicitação (aciona 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 necessário para este pedido.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54b268aa0e",
      "maxAmountRequired": "1250000",
      "payTo": "0x302afdd980aaefca3afa8df7222a6002774f6724",
      "extra": {
        "eip712": { "...": "..." }
      }
    }
  ],
  "paywall": { ... }
}

• network: deve ser base (rede principal Base);
• asset: endereço do contrato USDC na Base (exemplo do contrato oficial da rede principal);
• maxAmountRequired: unidade atômica de USDC necessária para este pagamento (1 USDC = 1.000.000 unidades atômicas);
• payTo: endereço de recebimento da plataforma, deve ser consistente com a página de detalhes do pedido;
• extra: informações do domínio EIP-712 necessárias para a assinatura, etc.

​

2. Gerar X-PAYMENT

1. Converter a chave privada da carteira de pagamento em um objeto de conta;
2. Registrar os dados accepts da resposta 402, escolhendo a opção de pagamento onde network == "base";
3. Chamar a função de assinatura fornecida pelo SDK para gerar a string X-PAYMENT codificada em Base64 (não é necessário conectar diretamente ao facilitador; o backend da plataforma será responsável por chamar o facilitador para concluir a verificação/liquidação);
4. Recomenda-se verificar se maxAmountRequired está dentro do intervalo aceitável, caso contrário, alertar o usuário para recarregar.

​

3. Repetir com a assinatura

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. Exemplos de Código em Múltiplas Linguagens

• ACE_PLATFORM_TOKEN：Token da Plataforma；
• ACE_X402_ORDER_ID：ID do Pedido；
• ACE_X402_PRIVATE_KEY：Chave privada da carteira de pagamento (com prefixo 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(`status inesperado ${initial.status}`);
  }

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

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

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

​

4. Python httpx（assíncrono）

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

asyncio.run(pay_order())

O exemplo apenas demonstra chamadas-chave, em ambiente de produção, por favor, adicione tratamento de exceções, estratégias de repetição, logs e controles de segurança.

​

Cinco, Verificação após o pagamento bem-sucedido

• Verificação no console: Acesse a página de detalhes do pedido https://platform.acedata.cloud/console/orders/{order_id}, se a página mostrar “Pagamento bem-sucedido” ou o status do pedido tiver mudado para pago/concluído, isso significa que a liquidação na blockchain foi concluída.
• Verificação da API: Chame GET https://platform.acedata.cloud/api/v1/orders/{order_id}/ e inclua Authorization: Bearer {platform_token}, verifique o campo state na resposta ( PAID ou FINISHED indica pagamento bem-sucedido).
• Cabeçalho de retorno: Leia X-PAYMENT-RESPONSE na resposta de pagamento bem-sucedido, pode-se decodificar o hash da transação na blockchain como o comprovante final; recomenda-se salvar essa informação nos logs do sistema para conciliação.

​

Seis, Resolução de Problemas Comuns

• Ainda retorna 402: Confirme se o endereço de pagamento possui USDC suficiente na rede Base, verifique se maxAmountRequired excede o saldo da carteira ou limite personalizado.
• Falha na assinatura: Certifique-se de que a chave privada tenha o prefixo 0x; ao assinar, use estritamente o extra (domínio EIP-712) e payTo da resposta, não altere a ordem dos campos.
• Rede não correspondente: Pode haver múltiplos requisitos em accepts, escolha a opção network === "base".
• Falta de X-PAYMENT-RESPONSE: Indica que o pagamento não foi realmente debitado, pode-se reiniciar com base no erro no corpo da resposta; se houver congestionamento na blockchain, tente novamente mais tarde.
• Token da plataforma inválido: Confirme se o Token não foi excluído e começa com o prefixo platform-v1-; se a interface retornar 401, pode-se regenerar no console.

​

Sete, Mais Ajuda

• Documentação online e perguntas frequentes: Navegação “Documentação” no topo do console da plataforma.
• Envio de tickets e suporte ao cliente: https://platform.acedata.cloud/support
• Comunidade: Discord https://discord.gg/f9GRuKCmRc, X (Twitter) https://x.com/acedatacloud
• Outros canais: E-mail office@acedata.cloud, office@germey.tech; endereço da empresa 651 N Broad St, Suite 201, Middletown, Delaware, EUA; para suporte via WeChat, consulte o código QR mais recente na página de suporte.
• Feedback e sugestões: Sinta-se à vontade para nos informar sobre necessidades de melhoria através de qualquer um dos canais acima.