| Internet-Draft | Payment Discovery | March 2026 |
| Moxey, et al. | Expires 4 September 2026 | [Page] |
This document defines discovery mechanisms for the "Payment" HTTP authentication scheme [I-D.httpauth-payment]. It specifies how clients can discover a server's payment capabilities before initiating requests, including supported payment methods, accepted currencies, and intents.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 4 September 2026.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The "Payment" HTTP authentication scheme [I-D.httpauth-payment] enables
servers to require payment for resource access. While the 402 response
with WWW-Authenticate: Payment header provides all information needed
to complete a paid exchange, clients may benefit from discovering payment
capabilities before making requests.¶
This specification defines an optional discovery mechanism using a well-known HTTP endpoint that returns structured payment capability information.¶
Discovery is OPTIONAL. Servers MAY implement this mechanism to improve client experience. Clients MUST NOT require discovery to function; the 402 challenge provides all information needed to complete payment.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
An identifier for an accepted unit of value, using the same formats
defined in the "charge" intent specification's Currency Formats
section. This includes ISO 4217 codes (e.g., "usd") and
method-defined identifiers (e.g., token contract addresses).¶
The process by which a client learns a server's payment capabilities before initiating a request that may require paid access.¶
The set of payment methods, intents, and accepted currencies that a server accepts as payment.¶
Servers MAY expose payment capabilities at the following location:¶
GET /.well-known/payment¶
The client issues a GET request to /.well-known/payment. The request
SHOULD include an Accept header with application/json:¶
GET /.well-known/payment HTTP/1.1 Host: api.example.com Accept: application/json¶
The server responds with a JSON object describing its payment capabilities.
The response MUST use Content-Type: application/json.¶
Response Schema:¶
| Field | Type | Required | Description |
|---|---|---|---|
version
|
integer | REQUIRED | Schema version. Currently 1. |
realm
|
string | OPTIONAL | Default realm for payment challenges. |
description
|
string | OPTIONAL | Human-readable description of the service. |
methods
|
object | REQUIRED | Map of supported payment methods. |
Method Object Schema:¶
Each key in methods is a registered payment method identifier. The value
is an object with:¶
| Field | Type | Required | Description |
|---|---|---|---|
intents
|
array | REQUIRED | Supported intent types. |
currencies
|
array | REQUIRED | Accepted currency identifiers, using the formats defined by the payment method specification (e.g., ISO 4217 codes, token addresses). |
Example Response:¶
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=300
{
"version": 1,
"realm": "api.example.com",
"description": "AI inference API",
"methods": {
"tempo": {
"intents": ["charge", "session"],
"currencies": ["0x20c0000000000000000000000000000000000000"]
},
"lightning": {
"intents": ["charge"],
"currencies": ["sat"]
}
}
}
¶
Servers SHOULD include Cache-Control headers with short durations to
allow clients to detect capability changes. A maximum age of 5 minutes
is RECOMMENDED:¶
Cache-Control: max-age=300¶
Longer durations (e.g., max-age=3600) MAY be used for capabilities that
change infrequently. Clients SHOULD respect cache headers and refetch
when capabilities may have changed (e.g., after receiving an unexpected
402 challenge for a method not in the cached discovery response).¶
Clients MUST check the version field before processing the response.
If the version value is higher than the version the client supports,
the client SHOULD treat the response as unsupported and fall back to
the 402 challenge flow. Clients MUST NOT assume forward compatibility
with unknown schema versions.¶
If the server does not support discovery, it SHOULD return 404 Not Found. Clients MUST NOT treat a 404 response as an error; it simply indicates discovery is unavailable.¶
Discovery information is advisory and not cryptographically authenticated. Clients MUST NOT rely on discovery for security decisions. The actual payment challenge in the 402 response is authoritative.¶
The well-known endpoint MUST be served over HTTPS. Clients MUST NOT accept discovery information over unencrypted HTTP.¶
Discovery endpoints reveal payment capabilities to unauthenticated clients. Servers should consider whether this information disclosure is acceptable.¶
Browser-based clients (e.g., wallets, payment agents) may need to access
the discovery endpoint cross-origin. Servers that intend to support
browser-based clients SHOULD include appropriate CORS headers
(e.g., Access-Control-Allow-Origin) on responses to
/.well-known/payment. This aligns with the cross-origin considerations
in Section 11.11 of [I-D.httpauth-payment].¶