Subscription Intent for HTTP Payment Authentication

1.1. Relationship to Payment Methods

Payment methods implement "subscription" using method-specific recurring authorization mechanisms. This document defines the abstract semantics and shared request fields. Payment method specifications define how those semantics are enforced, which request shapes they support, and which requests they reject because they cannot be represented exactly on the underlying payment network.¶

Payment method specifications MAY intentionally define a constrained subset of a richer underlying subscription system. A method MUST either preserve the semantics in this document exactly or reject the request; it MUST NOT approximate them.¶

Payment method specifications MAY also impose additional constraints that are not part of the shared contract, such as an explicit expiry or recipient requirements, when the underlying payment system cannot safely support the shared intent without them. Such constraints MUST be made explicit by the method specification.¶

4.1. Definition

The "subscription" intent represents a request for a recurring fixed-amount payment of amount, charged once per billing period until explicit cancellation or until the recurring authorization otherwise becomes invalid.¶

4.2. Properties

4.3. Flow

   Client                           Server                    Payment Network
      │                                │                              │
      │  (1) GET /resource             │                              │
      ├───────────────────────────────>│                              │
      │                                │                              │
      │  (2) 402 Payment Required      │                              │
      │      intent="subscription"     │                              │
      │<───────────────────────────────┤                              │
      │                                │                              │
      │  (3) Sign subscription grant   │                              │
      │                                │                              │
      │  (4) Authorization: Payment    │                              │
      ├───────────────────────────────>│                              │
      │                                │                              │
      │                                │  (5) Activate subscription   │
      │                                │      + collect first charge  │
      │                                ├─────────────────────────────>│
      │                                │                              │
      │  (6) 200 OK + Receipt          │                              │
      │<───────────────────────────────┤                              │
      │                                │                              │
      │        ... later period ...    │                              │
      │                                │                              │
      │                                │  (7) Collect renewal         │
      │                                ├─────────────────────────────>│
      │                                │                              │
      │  (8) 200 OK + Receipt          │                              │
      │<───────────────────────────────┤                              │
      │                                │                              │

5.1. Shared Fields

All payment methods implementing the "subscription" intent MUST support the required shared fields below. Method specifications MAY support, forbid, or elevate optional shared fields to REQUIRED, but MUST document those choices explicitly.¶

5.2. Currency Formats

The currency field supports multiple formats to accommodate different payment networks:¶

Payment method specifications MUST document which currency formats they support and how to interpret amounts for each format.¶

5.3. Method Extensions

Payment methods MAY define additional fields only in the methodDetails object. Shared top-level fields retain the meanings defined in this document.¶

5.4. Implementor Guidance

This section is non-normative.¶

Payment method authors should treat the shared subscription intent as the canonical interoperable contract between clients and servers. A method specification may intentionally define a narrower profile of its underlying payment system, but it should do so explicitly and fail closed.¶

In particular:¶

• Methods should support only request shapes they can represent exactly.¶

• Methods should document the supported and rejected ranges or values of periodUnit and periodCount, any additional bounded-lifetime or expiry rules they impose, and what conditions make activation succeed.¶

• Activation should not be reported as successful until both subscription setup and the first billing-period charge have succeeded.¶

• Methods should preserve the shared invariants of one successful charge per billing period, no automatic accumulation of missed periods, and no renewals after cancellation or any method-specific expiry.¶

• Richer network-native features such as trials, prorations, discounts, metered billing, pause or resume controls, quantity changes, plan changes, or open-ended renewals should be disabled or rejected unless the method specification defines an exact mapping that preserves the shared semantics.¶

• Implementations should maintain durable server state sufficient to prevent duplicate charges across retries, concurrent requests, and out-of-band network events.¶

5.5. Examples

{
  "amount": "9900",
  "currency": "usd",
  "periodUnit": "month",
  "periodCount": "1",
  "description": "Pro plan"
}

{
  "amount": "10000000",
  "currency": "0x20c0000000000000000000000000000000000001",
  "periodUnit": "day",
  "periodCount": "30",
  "subscriptionExpires": "2026-07-14T12:00:00Z",
  "recipient": "0x742d35cc6634c0532925a3b844bc9e7595f8fe00",
  "methodDetails": {
    "accessKey": {
      "accessKeyAddress": "0x1111111111111111111111111111111111111111",
      "keyType": "p256"
    },
    "chainId": 42431
  }
}

6.1. Payload

The credential payload for a "subscription" intent contains the subscription authorization grant. The format is method-specific:¶

6.2. Single-Use

Each "subscription" credential MUST be usable only once per challenge. Servers MUST reject replayed credentials.¶

A successfully activated subscription may be reused for later billing periods until:¶

• The payer explicitly cancels it¶

• The payment method revokes or invalidates the authorization¶

• The subscriptionExpires timestamp, if present, is reached¶

7.1. Activation

When the server receives a "subscription" credential, it MUST:¶

1. Verify the subscription authorization proof¶

2. Perform any method-specific subscription setup and collect the first billing-period charge¶

3. Initialize durable subscription state for later renewals¶

4. Return success (200) with a Payment-Receipt for the first charge, including a subscriptionId¶

The subscription becomes active only after these steps succeed.¶

7.2. Renewal

For each later billing period, the server MAY collect one renewal charge for amount using the method-specific recurring authorization flow.¶

If the server grants access for a later billing period, it MUST ensure that the renewal charge for that period has been collected before, or atomically with, delivering the corresponding service.¶

Servers MUST NOT collect more than one renewal charge for the same billing period.¶

If one or more billing periods elapse without a successful renewal charge, the subscription intent authorizes at most one charge for the then-current billing period. Servers MUST NOT treat missed billing periods as automatically accumulated authority for additional charges.¶

Payment method specifications define the concrete renewal, retry, recovery, and cancellation mechanisms, but they MUST preserve the invariants in this section.¶

7.3. Subscription Identifier

After successful activation, the server MUST return a subscriptionId in the Payment-Receipt. The value MUST be a base64url [RFC4648] string without padding and MUST be unique within the server's subscription namespace.¶

This specification does not define a dedicated request header or parameter for selecting an existing subscription. Selecting an existing subscription is an application-layer concern. Applications MAY use authenticated session state, account identity, resource scope, an application-defined selector, or other context to associate a later request with an existing subscription.¶

Clients MAY retain the subscriptionId as application data when referring to the active subscription in later interactions, but the subscriptionId is only a receipt identifier unless an application explicitly assigns it additional application-layer meaning.¶

Servers MUST authenticate or otherwise authorize the client's use of the identified subscription before granting access or collecting a renewal charge. Possession or presentation of a subscriptionId alone is insufficient.¶

7.4. Server Accounting and Idempotency

Servers MUST maintain durable subscription state sufficient to enforce per-period charging rules across retries and concurrent requests.¶

At minimum, servers MUST track:¶

• Subscription identifier¶

• Billing anchor or equivalent current billing-period start time¶

• Last successfully charged billing-period index, or whether the current billing period has been charged¶

• Any method-specific expiry or bounded-lifetime state¶

• Cancellation or revocation status¶

For non-idempotent requests, clients SHOULD send an Idempotency-Key header per [I-D.ietf-httpapi-idempotency-key-header]. Servers MUST NOT collect the same activation or renewal charge more than once for a duplicate idempotent request.¶

7.5. Cancellation

Payers SHOULD be able to cancel subscriptions before any applicable method-specific expiry. Cancellation mechanisms, effective-time rules, and any continued access for already-paid service are method-specific and MUST be documented by the payment method or application profile.¶

Servers MUST NOT collect renewal charges for billing periods after cancellation takes effect.¶

7.6. Error Responses

When a subscription cannot be used to fulfill a request, the server MUST return an appropriate HTTP status code:¶

For all 402 responses, the server MUST include a WWW-Authenticate header with a fresh challenge. Clients receiving a 402 after a previously valid subscription SHOULD treat the subscription as no longer usable and initiate a new subscription flow.¶

8.1. Monthly Billing Example

Suppose a server offers a plan with these request fields:¶

• amount = "9900"¶

• currency = "usd"¶

• periodUnit = "month"¶

• periodCount = "1"¶

If activation succeeds at 2026-01-15T12:03:10Z, that time becomes the billing anchor. The resulting billing periods are:¶

• Period 0: [2026-01-15T12:03:10Z, 2026-02-15T12:03:10Z)¶

• Period 1: [2026-02-15T12:03:10Z, 2026-03-15T12:03:10Z)¶

• Period 2: [2026-03-15T12:03:10Z, 2026-04-15T12:03:10Z)¶

Activation collects the Period 0 charge. Requests during Period 0 do not require another renewal charge. When Period 1 begins, the server may collect one renewal charge for Period 1 before, or atomically with, granting access for that period. After that renewal succeeds, additional requests during Period 1 do not permit another charge for Period 1.¶

If the same monthly plan activates at 2026-01-31T12:03:10Z, the resulting boundaries are computed from the January 31 anchor:¶

• Period 0: [2026-01-31T12:03:10Z, 2026-02-28T12:03:10Z)¶

• Period 1: [2026-02-28T12:03:10Z, 2026-03-31T12:03:10Z)¶

• Period 2: [2026-03-31T12:03:10Z, 2026-04-30T12:03:10Z)¶

8.2. Cancellation Example

Suppose the subscription above has already been charged through Period 2 and the payer cancels on 2026-03-20T09:00:00Z.¶

Cancellation takes effect at the end of the current paid billing period, which is 2026-04-15T12:03:10Z in this example. The server continues honoring access through that time. The server does not collect a renewal charge for Period 3. A request after 2026-04-15T12:03:10Z receives 402 Payment Required with a fresh challenge.¶

8.3. Failed Renewal Example

Suppose Period 3 begins and the server attempts the renewal charge for that period, but the method-specific payment step fails.¶

The server does not grant access for the unpaid period and returns 402 Payment Required with a fresh challenge. If a later retry during Period 3 succeeds, the server may then grant access for Period 3.¶

If Period 4 begins before any successful charge occurs, the subscription intent authorizes at most one charge for Period 4. The missed Period 3 charge does not automatically accumulate into authority to collect both Period 3 and Period 4.¶

8.4. Expiry Example

The shared subscription intent defines subscriptionExpires as an optional top-level field. Some payment methods require it and others leave it optional.¶

Once subscriptionExpires is reached, the server stops treating the subscription as reusable for future billing periods. Requests after that time receive 402 Payment Required with a fresh challenge.¶

9.1. Recurring Charge Awareness

Clients MUST clearly communicate that a subscription authorizes future recurring charges without requiring a new user action for each billing period.¶

9.2. Amount and Period Verification

Clients MUST verify before activating a subscription:¶

1. amount is acceptable for the service¶

2. currency is expected¶

3. periodUnit and periodCount match the expected billing interval¶

4. Any subscriptionExpires value and method-specific constraints are understood and acceptable¶

Clients MUST NOT rely on the description field for payment verification.¶

9.3. Duplicate Charge Prevention

Servers MUST prevent duplicate activation and renewal charges caused by retries, parallel requests, or races between charging and service delivery.¶

9.4. Server Accountability

Servers operating subscriptions are responsible for:¶

• Secure storage of subscription authorization data¶

• Not charging more than once per billing period¶

• Honoring cancellation and revocation¶

• Providing transaction or billing records to payers¶

9.5. Caching

Responses to subscription challenges (402 Payment Required) MUST include Cache-Control: no-store to prevent sensitive payment data from being cached by intermediaries.¶

Responses containing Payment-Receipt headers MUST include Cache-Control: private to prevent shared caches from storing payment receipts.¶

10.1. Payment Intent Registration

This document registers the "subscription" intent in the "HTTP Payment Intents" registry established by [I-D.httpauth-payment]:¶

Contact: Tempo Labs (contact@tempo.xyz)¶