Charge Intent for HTTP Payment Authentication

1.1. Relationship to Payment Methods

This document defines the abstract semantics of the "charge" intent. Payment method specifications define how to implement this intent using their specific payment infrastructure.¶

4.1. Definition

The "charge" intent represents a request for immediate, one-time payment of a specified amount in exchange for resource access.¶

4.2. Properties

4.3. Flow

1. Server issues a 402 response with intent="charge"¶

2. Client fulfills the payment (method-specific)¶

3. Client submits credential with proof of payment¶

4. Server verifies payment and grants access¶

5. Server returns Payment-Receipt header¶

4.4. Atomicity

The "charge" intent implies atomic exchange: the server SHOULD NOT provide partial access if payment verification fails. Either the full resource is provided (payment succeeded) or access is denied (payment failed).¶

5.1. Shared Fields

All payment methods implementing the "charge" intent MUST support these shared fields, enabling clients to parse and display payment requests consistently across methods. Payment methods MAY elevate OPTIONAL fields to REQUIRED in their method specification (e.g., recipient and expires are REQUIRED for blockchain methods).¶

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 in the methodDetails object. These fields are method-specific and MUST be documented in the payment method specification. Clients that do not recognize a payment method SHOULD ignore methodDetails but MUST still be able to display the shared fields to users.¶

5.4. Examples

{
  "amount": "5000",
  "currency": "usd",
  "description": "Premium API access",
  "externalId": "order_12345",
  "methodDetails": {
    "networkId": "profile_1MqDcVKA5fEO2tZvKQm9g8Yj",
    "paymentMethodTypes": ["card", "link"]
  }
}

{
  "amount": "1000000",
  "currency": "0x20c0000000000000000000000000000000000000",
  "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
  "methodDetails": {
    "chainId": 42431,
    "feePayer": true
  }
}

{
  "amount": "100000",
  "currency": "sat",
  "methodDetails": {
    "invoice": "lnbc1000n1pj9..."
  }
}

6.1. Payload

The credential structure follows [I-D.httpauth-payment], containing challenge, payload, and an optional source field identifying the payer. The payload for a "charge" intent MUST contain proof that payment has been made or authorized. The proof type is method-specific:¶

6.2. Single-Use

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

7.1. Server Responsibilities

Servers verifying a "charge" credential MUST:¶

1. Verify the id matches an outstanding challenge¶

2. Verify the challenge has not expired¶

3. Verify the payment proof using method-specific procedures¶

4. Verify the payment amount matches the request¶

5. Verify the payment recipient matches the request¶

7.2. Settlement

Settlement semantics differ by method:¶

• Immediate settlement: Payment is final upon verification (e.g., Lightning preimage, confirmed blockchain transaction)¶

• Deferred settlement: Server submits payment after verification (e.g., signed authorization submitted to chain)¶

• Processor settlement: External processor handles settlement (e.g., Stripe PaymentIntent)¶

8.1. Amount Verification

Clients MUST verify the requested amount is appropriate for the resource before authorizing payment. Malicious servers could request excessive amounts.¶

8.2. Recipient Verification

Clients SHOULD verify the payment recipient when possible. Not all payment methods expose an explicit recipient (e.g., processor-based methods like Stripe route payments internally). For methods that do expose a recipient (e.g., blockchain addresses), clients SHOULD warn users about unknown recipients.¶

8.3. Replay Protection

Servers MUST implement replay protection. Each challenge id MUST be single-use. Servers MUST NOT accept the same credential twice.¶

8.4. Finality

The finality of a "charge" payment depends on the payment method:¶

• Some methods provide instant finality (Lightning)¶

• Some methods may have delayed finality (blockchain confirmations)¶

• Some methods may be reversible (card chargebacks)¶

Servers SHOULD understand the finality guarantees of their accepted payment methods and adjust resource access accordingly.¶

8.5. Transport Security

All Payment authentication flows MUST use TLS 1.2 or later per [I-D.httpauth-payment]. Payment credentials contain sensitive authorization data that could result in financial loss if intercepted.¶

8.6. Currency Verification

Clients MUST verify the currency field matches their expectation before authorizing payment. Malicious servers could request payment in a different currency or token than expected.¶

9.1. Payment Intent Registration

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

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