> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# X402-guide för orderbetalning

> Platform API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/orders), 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](https://platform.acedata.cloud/console/platform-tokens) och skapa en token i formatet `platform-v1-...`.

Använd följande i efterföljande begäranden:

```http theme={null}
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`:

```http theme={null}
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`:

```json theme={null}
{
  "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.

```text theme={null}
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:

```ts theme={null}
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:

```text theme={null}
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:

```text theme={null}
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`:

```json theme={null}
{
  "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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.