Charge Intent for HTTP Payment Authentication

Introduction The "charge" intent is the most fundamental payment pattern: a one-time exchange of payment for resource access. The payer provides proof of payment (or a signed authorization to collect payment), and the server grants access to the requested resource. This intent applies to any payment method that supports immediate payment verification, including: Invoice-based systems (preimage revelation) Signed transaction authorization Token-based payment confirmation Traditional payment processor confirmation

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.

Requirements Language 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 when, and only when, they appear in all capitals, as shown here.

Terminology

Charge: A one-time payment where the payer provides proof of payment immediately in exchange for resource access.
Base Units: The smallest denomination of a currency or asset. For USD, this is cents (1/100). For tokens, this is the smallest transferable unit defined by the token's decimal precision.

Intent Semantics

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

Properties Property Value Intent Identifier charge Payment Timing Immediate (before or with request) Idempotency Single-use per challenge Reversibility Method-dependent

Flow Server issues a 402 response with intent="charge" Client fulfills the payment (method-specific) Client submits credential with proof of payment Server verifies payment and grants access Server returns Payment-Receipt header

Atomicity The "charge" intent implies atomic exchange: the server MUST NOT provide partial access if payment verification fails. Either the full resource is provided (payment succeeded) or access is denied (payment failed). This aligns with the unpaid-request side-effect boundary already required by under "Idempotency and Side Effects". Partial access includes, but is not limited to: Any response body bytes, including a partial buffered payload Streamed output, including the first token or chunk of a streaming response Invocation of tools, functions, or external APIs on behalf of the request Initiation of an asynchronous task, job, or subscription If verification fails after any such effect has already occurred, the server MUST treat this as an implementation defect to be corrected, not as a conforming outcome; there is no MAY-level exception for "already-started" delivery.

Request Schema The request parameter for a "charge" intent is a JSON object with shared fields defined by this specification and optional method-specific extensions in the methodDetails field. The request JSON MUST be serialized using JSON Canonicalization Scheme (JCS) and base64url-encoded without padding per .

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).

Required Fields Field Type Description amount string Payment amount in base units (smallest denomination) currency string Currency or asset identifier (see )

Optional Fields Field Type Description recipient string Payment recipient in method-native format description string Human-readable payment description externalId string Merchant's reference (order ID, invoice number, etc.) methodDetails object Method-specific extension data Challenge expiry is conveyed by the expires auth-param in WWW-Authenticate per , using format. Request objects MUST NOT duplicate the expiry value.

Currency Formats The currency field supports multiple formats to accommodate different payment networks: Format Example Description ISO 4217 "usd", "eur" Fiat currencies (lowercase) Token address "0x20c0..." On-chain token contract address Method-defined (varies) Payment method-specific currency identifiers Payment method specifications MUST document which currency formats they support and how to interpret amounts for each format.

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.

Examples

Traditional Payment Processor (Stripe)

Blockchain Payment (Tempo)

Lightning Network

Payment method specifications define the complete methodDetails schema for their implementation of the "charge" intent.

Credential Requirements

Payload The credential structure follows , 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: Proof Type Description Example Methods Preimage Hash preimage proving invoice payment Lightning Signature Signed transaction authorization Tempo, EVM Confirmation Payment processor confirmation identifier Stripe Ledger transaction Transaction hash on public ledger Bitcoin, Ethereum

Single-Use Each credential MUST be usable only once per challenge. Servers MUST reject replayed credentials.

Verification

Server Responsibilities Servers verifying a "charge" credential MUST: Verify the id matches an outstanding challenge Verify the challenge has not expired Verify the payment proof using method-specific procedures Verify the payment amount matches the request Verify the payment recipient matches the request

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)

Security Considerations

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

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.

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

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.

Transport Security All Payment authentication flows MUST use TLS 1.2 or later per . Payment credentials contain sensitive authorization data that could result in financial loss if intercepted.

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.

IANA Considerations

Payment Intent Registration This document registers the "charge" intent in the "HTTP Payment Intents" registry established by : Intent Description Reference charge One-time immediate payment This document Contact: Tempo Labs (contact@tempo.xyz)