Ako funguje x402 V2: hlavičky, schémy a overenie

V2 rozširuje x402 z jedného „zaplať presnú sumu“ toku na modulárny protokol. Základ však zostáva malý: server opíše prijateľnú platbu, klient vytvorí payload a server ho overí pred vydaním zdroja.

Tri hlavičky, ktoré treba poznať

Názvy hlavičiek sú súčasťou wire formátu V2. Staršie príklady môžu používať X-PAYMENT; pri integrácii preto vždy kontrolujte verziu SDK aj protokolu.

PaymentRequired

Odpoveď 402 môže ponúknuť viac spôsobov platby. Každá možnosť viaže schému na sieť, aktívum, sumu a príjemcu.

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "10000",
      "payTo": "0x51bd..."
    }
  ]
}

Hodnota network vo V2 používa CAIP pomenovanie. Klient nesmie predpokladať počet desatinných miest ani význam sumy bez znalosti aktíva.

Schéma nie je sieť

Schéma opisuje logiku platby. Sieť určuje, ako sa táto logika podpíše, overí a vyrovná.

• exact prenesie presne stanovenú sumu,
• upto autorizuje horný limit a server vyúčtuje skutočnú spotrebu,
• batch-settlement umožňuje zlučovať veľa malých poplatkov do neskoršieho vyrovnania.

Podpora názvu schémy sama nestačí. Klient aj facilitátor musia podporovať konkrétnu dvojicu schémy a siete.

Overenie pred vykonaním práce

Resource server má dve možnosti:

1. overiť payload lokálne,
2. poslať payload a pôvodné podmienky na /verify facilitátora.

Overenie má potvrdiť minimálne podpis, súlad s podmienkami, platnosť autorizácie a ochranu pred opakovaným použitím. Až potom je bezpečné vykonať platenú operáciu.

<?php

// Ilustračný pseudokód, nie hotové produkčné middleware.
$requirements = decodeHeader($_SERVER['HTTP_PAYMENT_REQUIRED'] ?? '');
$payload = decodeHeader($_SERVER['HTTP_PAYMENT_SIGNATURE'] ?? '');

$verification = $facilitator->verify($payload, $requirements);

if (!$verification->isValid()) {
    http_response_code(402);
    exit;
}

$result = runPaidOperation();
$settlement = $facilitator->settle($payload, $requirements);

Vyrovnanie a odpoveď

Po úspešnom overení server vykoná prácu a zabezpečí vyrovnanie. Poradie je produktové aj rizikové rozhodnutie: niektoré služby potrebujú istotu platby pred drahým výpočtom, iné uprednostnia nižšiu latenciu.

Ak klient zopakuje rovnakú požiadavku po strate spojenia, nesmie automaticky zaplatiť dvakrát za jednu logickú operáciu. Idempotency kľúč patrí do návrhu od prvého dňa.

Úspešná odpoveď môže niesť potvrdenie:

HTTP/1.1 200 OK
Content-Type: application/json
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLC...

Kontrolný zoznam implementácie

• Zamknite podporovanú verziu protokolu a balíkov.
• Validujte URL, metódu, cenu, aktívum, sieť a príjemcu.
• Nikdy nelogujte celé podpisové payloady do bežného aplikačného logu.
• Nastavte krátku platnosť autorizácie a ochranu pred replay.
• Zaveďte idempotenciu pre POST a drahé operácie.
• Rozlišujte chybu platby, chybu facilitátora a chybu vlastnej služby.
• Testujte výpadok medzi overením, vykonaním práce a vyrovnaním.

Normatívne detaily schém sú v adresári specs/schemes oficiálneho repozitára.