/verify i /settle Facilitatora.
Produkcyjny adres Facilitatora Ace Data Cloud to:
Konwencje wire v2
Łańcuch X402 Ace Data Cloud w całości używa oficjalnego x402 v2 i nie akceptuje już nagłówka żądaniaX-Payment z v1. Podczas integracji należy zwrócić uwagę na trzy punkty:
- Nagłówkiem żądania jest
PAYMENT-SIGNATURE, a jego wartością jest envelope JSON zakodowany w base64. - Na najwyższym poziomie envelope musi znajdować się
x402Version: 2, a wybrane w tym przypadkuschemeinetworknależy zadeklarować za pomocą obiektuaccepted. networkużywa identyfikatora CAIP-2 (np.eip155:8453), nie można zapisywać skrótów takich jakbase.
PAYMENT-REQUIRED, którego wartością jest ta sama treść wyzwania zakodowana w base64, co ułatwia klientowi odczytanie wymagań płatności bez parsowania body.
Kluczowe interfejsy
GET /supported
Sprawdź obsługiwane sieci i scheme:
networkużywa identyfikatora CAIP-2, a nie skrótów takich jakbaseczysolana./supportedoznacza, że Facilitator posiada odpowiednie możliwości weryfikacji i rozliczania.- Base i Solana obsługują
exact;uptojest obecnie dostępne tylko na Base. signersto adresy używane przez Facilitator do wysyłania transakcji rozliczeniowych.- To, czy konkretne API zezwala na te opcje, nadal zależy od
acceptsw odpowiedzi 402 tego API.
POST /verify
Zweryfikuj, czy PAYMENT-SIGNATURE przesłany przez klienta spełnia określony payment requirement.
Body żądania:
paymentRequirements w v2 to scheme, network, asset, amount, payTo, maxTimeoutSeconds i extra, a pole kwoty to amount. W accepts[] odpowiedzi API 402 zwracane jest dodatkowo maxAmountRequired, aby klient mógł odczytać limit, ale nie należy ono do pól body żądania Facilitatora.
Pomyślna odpowiedź:
PAYMENT-RESPONSE dla płatności zamówienia produkcyjnego zawiera on wynik settlement. Wynik działania programu dla płatności zamówienia Base:
success=Trueoznacza, że settlement Facilitatora zakończył się sukcesem.transactionjest hashem transakcji on-chain, apay_idzamówienia jest również zapisywane z tą samą wartością.- W explorer można zobaczyć transfer
1200000atomic USDC Base. errorReason=Noneoznacza, że ten settlement nie zwrócił błędu biznesowego.
isValid ma wartość false. Strona biznesowa powinna odczytać invalidReason, zamiast patrzeć wyłącznie na kod statusu HTTP.
POST /settle
Rozlicz on-chain autoryzację, która została już zweryfikowana.
Body żądania jest zasadniczo takie samo jak dla /verify. Różnica dla upto polega na tym, że paymentRequirements.amount jest podczas settle nadpisywane rzeczywistą kwotą rozliczenia; limit podpisu jest rejestrowany przez Facilitator na etapie verify, a podczas settle sprawdzane jest, czy rzeczywista kwota nie przekracza tego limitu.
Pomyślna odpowiedź:
upto wynosi 0, transaction może być pustym ciągiem znaków, co oznacza, że nie trzeba wysyłać transakcji on-chain.
Jak Ace Data Cloud Gateway używa Facilitatora
Łańcuch API Gateway Ace Data Cloud wygląda następująco:- Klient po raz pierwszy wysyła żądanie API bez
AuthorizationiPAYMENT-SIGNATURE. - Gateway oblicza szacowaną cenę żądania i zwraca 402 oraz
accepts. - Po podpisaniu klient ponawia próbę z
PAYMENT-SIGNATURE. - Gateway dekoduje
PAYMENT-SIGNATUREi wybiera pasujący payment requirement. - Gateway wywołuje
/verifyFacilitatora. - Po powodzeniu
/verifyGateway przepuszcza żądanie do docelowego API. - Po zwróceniu odpowiedzi przez docelowe API Gateway wywołuje
/settleFacilitatora na etapie/record. - Gateway zapisuje hash transakcji on-chain w metadata rekordu użycia.
exact rozlicza kwotę podpisaną w kroku 7; upto zapisuje amount według rzeczywistego użycia w kroku 7, a następnie rozlicza rzeczywistą kwotę.
Jak zintegrować własne API
Jeśli chcesz, aby twoje własne API obsługiwało X402, możesz zaimplementować je według tej struktury:- Przygotuj
paymentRequirementsdla każdego płatnego interfejsu, zawierające sieć, kwotę, adres odbiorcy, adres aktywa i domain podpisu. - Jeśli żądanie nie ma
PAYMENT-SIGNATURE, zwróć HTTP 402 iaccepts. - Jeśli żądanie ma
PAYMENT-SIGNATURE, zdekoduj Base64, aby uzyskaćpaymentPayload. - Wywołaj Facilitator
/verify. - Po pomyślnej weryfikacji wykonaj logikę biznesową.
- Po pomyślnym wykonaniu logiki biznesowej wywołaj Facilitator
/settle. - Zapisz
payer,transaction,amount,networkna potrzeby uzgadniania.
paymentRequirements do wywołania /verify i /settle, nie ufaj kwocie, adresowi odbiorcy ani adresowi aktywa zwróconym przez klienta.
Ochrona przed ponownym odtworzeniem
Facilitator zapisuje nonce. Autoryzacja z tym samym nonce nie może być ponownie weryfikowana i rozliczana. Oznacza to:- Klient powinien przy każdym żądaniu podpisywać nowy envelope;
- Jeśli
/settleprzesłało już transakcję, ale tymczasowo nie ma potwierdzenia, można ponowić/settlez tym samym nonce, aby wykonać idempotentne uzgodnienie; - Nie przechowuj tego samego
PAYMENT-SIGNATUREw pamięci podręcznej i nie używaj go do wielu wywołań API.

