X402-guide för orderbetalning

Utöver att betala direkt per API-begäran stöder Ace Data Cloud också betalning av kontrollpanelsordrar med X402. Orderbetalning och API-anrop använder samma kärnprotokoll: den första begäran returnerar 402, klienten signerar PAYMENT-SIGNATURE och försöker sedan igen med samma begäran. Skillnaden är att orderbetalning tillhör plattformens API och kräver en kontotoken; medan direktanrop till AI API:t x402.acedata.cloud kan använda enbart X402 och inte kräver någon API-token.

Förbered ordern

Gå till Ace Data Cloud-kontrollpanelen, välj ordern som ska betalas och notera order-ID:t. Om du ännu inte har någon order kan du skapa en obetald order på paketsidan. Orderpriset följer det som visas på sidan, och amount i X402 402-svaret är den slutgiltiga grunden för signeringen.

Skapa kontotoken

Begäran om orderbetalning kräver en kontotoken. Öppna plattformens Token-sida och skapa en token i formatet platform-v1-.... Använd följande i efterföljande begäranden:

Authorization: Bearer {platform_token}

Kontotoken skiljer sig från vanlig API-token. Vanlig API-token används för att förbruka API-kvot; kontotoken används för att representera ditt konto vid hantering av plattformsresurser, såsom orderbetalning.

Utlös 402

Skicka först en begäran utan PAYMENT-SIGNATURE:

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

{
  "pay_way": "X402"
}

Returneringsstatusen är 402 och svaret innehåller accepts:

{
  "x402Version": 2,
  "error": "Payment required for this order.",
  "resource": {
    "url": "http://platform.acedata.cloud/api/v1/orders/.../pay/",
    "description": "Ace Data Cloud Credits x 10.0",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "1200000",
      "payTo": "0x...",
      "maxTimeoutSeconds": 120,
      "extra": {
        "name": "USD Coin",
        "version": "2",
        "chainId": 8453,
        "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "decimals": 6
      }
    }
  ],
  "paywall": {
    "app_name": "Ace Data Cloud",
    "app_logo": "https://cdn.acedata.cloud/favicon.ico"
  }
}

Orderbetalning använder officiell x402 v2: x402Version är 2, network använder CAIP-2-identifierare och beloppsfältet är amount. Programkörningsresultat för att skapa en order på 10 Credits och utlösa 402:

Följande transaktionsposter är historiska praktiska testexempel från den gamla policyn. Belopp och transaktionshashar behålls oförändrade. Nya X402-order har inte längre rabatt för betalningsmetod; använd amount i det aktuella 402-svaret som grund för signering och betalning.

created order 78481793-304e-47f7-bc0c-8231aec9cc1e
created state Pending
created price 1.26

http_status=402
x402Version 2
error Payment required for this order.
accepts [
  ('eip155:8453', 'exact', '1200000', '0x4F0E2D3477a1B94CF33d16E442CEe4733dadCeE7'),
  ('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', 'exact', '1200000', '5iVXFrYaYWX2GUTbkQj8mDBoBhAX8bneYigS2LJTia43')
]
description Ace Data Cloud Credits x 10.0

Resultatförklaring:

Efter att ordern har skapats är statusen Pending, och det har ännu inte skett någon betalning på kedjan.
Den första pay/-begäran innehåller inte PAYMENT-SIGNATURE, därför returneras HTTP 402.
accepts anger både Base exact och Solana exact; denna guide väljer Base i fortsättningen.
Orderpriset vid skapandet var 1.26. Vid betalning under den gamla rabattpolicyn för X402-betalning var det faktiska signerade och avräknade beloppet 1.2 USDC, motsvarande 1200000 atomic USDC.

Observera att resource här är ett fält som returneras av servern och deltar i signeringen; klienten ska inte själv ändra protokoll, sökväg eller order-ID i det.

Signera och försök igen

Orderbetalning kan återanvända signeringsfunktionerna på låg nivå i @acedatacloud/x402-client eller acedatacloud-x402. Nedan följer ett TypeScript-exempel:

import { Wallet } from 'ethers';
import { signEVMPayment } from '@acedatacloud/x402-client';

const platformToken = process.env.ACE_PLATFORM_TOKEN!;
const orderId = process.env.ACE_ORDER_ID!;
const wallet = new Wallet(process.env.EVM_PRIVATE_KEY!);

const url = `https://platform.acedata.cloud/api/v1/orders/${orderId}/pay/`;
const body = { pay_way: 'X402' };

const first = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${platformToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
});

if (first.status !== 402) {
  throw new Error(`expected 402, got ${first.status}`);
}

const paymentRequired = await first.json();
const requirement = paymentRequired.accepts.find(
  (item: any) => item.network === 'eip155:8453' && item.scheme === 'exact'
);

const evmProvider = {
  async request({ method, params }: { method: string; params?: unknown[] }) {
    if (method !== 'eth_signTypedData_v4') throw new Error(`unsupported method: ${method}`);
    const [, typedDataJson] = params as [string, string];
    const typedData = JSON.parse(typedDataJson);
    return wallet.signTypedData(typedData.domain, typedData.types, typedData.message);
  }
};

const envelope = await signEVMPayment(requirement, evmProvider, wallet.address);
const xPayment = Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64');

const paid = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${platformToken}`,
    'Content-Type': 'application/json',
    'PAYMENT-SIGNATURE': xPayment
  },
  body: JSON.stringify(body)
});

if (!paid.ok) {
  throw new Error(`payment failed: ${paid.status} ${await paid.text()}`);
}

console.log(await paid.json());

Programkörningsresultat efter signering och nytt försök med Base exact för samma order:

status 200
payer 0x5d4f08D5c2bb60703284bc06671Eb680fA41B105
has_x_payment_response True
settle_header {'success': True, 'network': 'base', 'transaction': '0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151', 'errorReason': None}
order {'id': '78481793-304e-47f7-bc0c-8231aec9cc1e', 'state': 'Finished', 'pay_way': 'X402', 'price': 1.2, 'pay_id': '0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151'}

Resultat för bekräftelse på kedjan:

tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
status 1
block 46726704
explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
transfer {"from":"0x5d4f08D5c2bb60703284bc06671Eb680fA41B105","to":"0x4F0E2D3477a1B94CF33d16E442CEe4733dadCeE7","value":"1200000"}

Resultatförklaring:

status 200 anger att plattformens betalnings-API för order accepterade denna PAYMENT-SIGNATURE.
has_x_payment_response True anger att svarshuvudet innehåller ett Base64-kodat PAYMENT-RESPONSE-kvitto.
settle_header.success=True och network=base anger att Facilitator har slutfört Base settlement.
Orderns slutliga status är Finished, pay_way är X402, och pay_id skrivs som transaktionshashet på kedjan.
Händelsen Transfer på BaseScan visar att betalningsadressen överförde 1200000 atomic USDC till plattformens mottagaradress, alltså 1.2 USDC.

Lyckat svar och kvitto

När orderbetalningen har lyckats är svarskroppen orderinformation. Plattformen skickar även ett Base64-kodat settlement response i svarshuvudet PAYMENT-RESPONSE; efter avkodning omfattar vanliga fält:

Fält	Beskrivning
`success`	Om Facilitator settlement lyckades.
`transaction`	Transaktionshash för settlement på kedjan.
`network`	Betalningsnätverk.
`payer`	Betalande plånboksadress.
`amount`	Faktiskt settlement-belopp, med atomic units.

Om du behöver avstämning rekommenderas att samtidigt spara order-ID, betalande plånboksadress, transaction och orderns slutliga status.

Observera

Orderbetalning kräver en plattformskontotoken och kan inte slutföras enbart med X402-plånbokssignaturen.
amount använder USDC atomic units, där 1200000 motsvarar 1.2 USDC.
Sätt inte ihop mottagaradressen eller tillgångsadressen själv; utgå från accepts i 402-svaret.
Om samma PAYMENT-SIGNATURE skickas in upprepade gånger använder Facilitator nonce för replay-skydd.

Svar vid betalningsfel

Den första HTTP 402 utan PAYMENT-SIGNATURE är en normal betalningsutmaning och innebär inte att betalningen har misslyckats. Verifierings- eller settlement-fel efter signering behåller fortfarande standardsträngen error som en kompatibilitetsreserv och returnerar en stabil felstruktur i extensions.acedatacloud.paymentError:

{
  "code": "insufficient_token_balance",
  "params": { "network": "eip155:8453" },
  "stage": "verify",
  "retryable": true,
  "charged": false
}

Klienten bör i första hand lokalisera enligt code; okända code ska falla tillbaka till ett generellt betalningsfel. charged är ett trelägesfält: false returneras endast när betalningen uttryckligen nekas före settlement; om fältet saknas är debiteringsstatusen okänd och får inte tolkas som ”inte debiterad”. När den aktuella ordern har gått in i Failed kan den inte försöka igen med samma order; skapa en ny order efter att ha åtgärdat plånboksproblemet. Logga eller skicka inte in fullständig PAYMENT-SIGNATURE, plånbokssignatur, auktoriserings-payload, Facilitators råa diagnostik eller RPC-svar. Kundtjänstens felsökning behöver endast order-ID och den offentliga fel-code.

Getting Started

AI Samtal

AI Bild

AI Video

AI Ljud

Web & Data

CAPTCHA

Identitet

Coding

Fler guider

X402-guide för orderbetalning

Förbered ordern

Skapa kontotoken

Utlös 402

Signera och försök igen

Lyckat svar och kvitto

Observera

Svar vid betalningsfel

​Förbered ordern

​Skapa kontotoken

​Utlös 402

​Signera och försök igen

​Lyckat svar och kvitto

​Observera

​Svar vid betalningsfel

Förbered ordern

Skapa kontotoken

Utlös 402

Signera och försök igen

Lyckat svar och kvitto

Observera

Svar vid betalningsfel