diff --git a/specs/transports-v2/http.md b/specs/transports-v2/http.md index a735f80032..ddba4c9425 100644 --- a/specs/transports-v2/http.md +++ b/specs/transports-v2/http.md @@ -11,6 +11,11 @@ The server indicates payment is required using the HTTP 402 "Payment Required" s **Mechanism**: HTTP 402 status code with `PAYMENT-REQUIRED` header **Data Format**: Base64-encoded `PaymentRequired` schema in header +The `PAYMENT-REQUIRED` header is the canonical HTTP transport location for the +`PaymentRequired` object. A response body may duplicate the same information +for humans or backward compatibility, but clients and crawlers must not depend +on the body alone for x402 protocol data. + **Example:** ```http diff --git a/specs/x402-specification-v2.md b/specs/x402-specification-v2.md index 470bb9a9ca..b3727597a5 100644 --- a/specs/x402-specification-v2.md +++ b/specs/x402-specification-v2.md @@ -69,7 +69,9 @@ This section defines the core data structures used in the x402 protocol. These a **5.1.1 JSON Payload** -When a resource server requires payment, it responds with a payment required signal and a JSON payload containing payment requirements. Example: +When a resource server requires payment, it responds with a payment required signal containing the `PaymentRequired` object. The transport defines where this object is carried. For HTTP, the canonical wire location is the base64-encoded `PAYMENT-REQUIRED` response header, not only the response body. See [HTTP Payment Required Signaling](./transports-v2/http.md#payment-required-signaling). + +Example `PaymentRequired` object: ```json {