<!--
Sitemap:
- [MPP — Machine Payments Protocol](/index): MPP (Machine Payments Protocol) is the open standard for machine-to-machine payments—co-developed by Tempo and Stripe. Charge for API requests, tool calls, and content via HTTP 402.
- [Page Not Found](/404)
- [Brand assets and guidelines](/brand): Download official MPP logos, wordmarks, and brand assets. Guidelines for using the Machine Payments Protocol brand in your project or integration.
- [Extensions](/extensions): Community-built tools and integrations for MPP
- [Frequently asked questions](/faq): Answers to common questions about MPP—payment methods, settlement, pricing, security, and how the protocol compares to API keys and subscriptions.
- [Machine Payments Protocol](/overview): MPP standardizes HTTP 402 for machine-to-machine payments. Learn how agents, apps, and services exchange payments in the same HTTP request.
- [Payment methods](/payment-methods/): Available methods and how to choose one
- [Protocol overview](/protocol/): The Machine Payments Protocol standardizes HTTP 402 with an extensible challenge–credential–receipt flow that works with any payment network.
- [Quickstart](/quickstart/): Get started with MPP in minutes. Protect your API with payments, connect your agent, or integrate your app with MPP-enabled services.
- [SDKs and client libraries](/sdk/): Official MPP SDKs in TypeScript, Python, and Rust, plus community SDKs in other languages.
- [Discovery](/advanced/discovery): Advertise your API's payment terms with an OpenAPI discovery document so clients and agents know what endpoints cost before making requests.
- [Identity](/advanced/identity): Use MPP Credentials for access control, rate limiting, and multi-step workflows—without requiring payment.
- [Refunds](/advanced/refunds): Return funds to clients after a charge, or let sessions refund unused deposits automatically.
- [Build with an LLM](/guides/building-with-an-llm): Use llms-full.txt to give your agent complete MPP context.
- [Accept multiple payment methods](/guides/multiple-payment-methods): Accept Tempo stablecoins, Stripe cards, and Lightning Bitcoin on a single API endpoint. Serve a multi-method 402 Challenge and let clients choose.
- [Accept one-time payments](/guides/one-time-payments): Charge per request with a payment-gated API
- [Accept pay-as-you-go payments](/guides/pay-as-you-go): Build a payment-gated API with session-based billing using mppx payment channels. Charge per request with near-zero latency overhead.
- [Create a payment link](/guides/payment-links): Create a payment link for any API endpoint. Share it anywhere—users pay directly from the page, no integration required.
- [Proxy an existing service](/guides/proxy-existing-service): Put a payment gate in front of any API without changing its code. Use the mppx Proxy SDK to charge for upstream access.
- [Accept split payments](/guides/split-payments): Distribute a charge across multiple recipients
- [Accept streamed payments](/guides/streamed-payments): Accept streamed payments over Server-Sent Events with mppx. Bill per token in real time using Tempo payment channels for LLM inference APIs.
- [Upgrade your x402 server to MPP](/guides/upgrade-x402): Add MPP to your x402 server to unlock multi-method payments, sessions, and IETF standardization—without changing your business logic.
- [Charge intent for one-time payments](/intents/charge): Immediate one-time payments
- [Card payment method](/payment-methods/card/): Card payments via encrypted network tokens
- [Custom payment methods](/payment-methods/custom): Build your own payment method
- [Lightning](/payment-methods/lightning/): Bitcoin payments over the Lightning Network
- [Solana](/payment-methods/solana/): Native SOL and SPL token payments
- [Stellar SEP-41 token payments](/payment-methods/stellar/): SEP-41 token payments on the Stellar network
- [Stripe payment method](/payment-methods/stripe/): Cards, wallets, and other Stripe supported payment methods
- [Tempo stablecoin payments](/payment-methods/tempo/): Stablecoin payments on the Tempo blockchain
- [Challenges](/protocol/challenges): Server-issued payment requirements
- [Credentials](/protocol/credentials): Client-submitted payment proofs
- [HTTP 402 payment required](/protocol/http-402): HTTP 402 Payment Required signals that a resource requires payment. Learn when and how MPP servers return 402 with a WWW-Authenticate Challenge.
- [Payment receipts and verification](/protocol/receipts): Receipts confirm successful payment in MPP. Return them in the Payment-Receipt header so clients can verify that the server accepted their Credential.
- [Transports](/protocol/transports/): MPP defines transport bindings for HTTP and MCP. Learn how Challenges, Credentials, and Receipts map to headers and JSON-RPC messages.
- [Use with agents](/quickstart/agent): Connect your coding agent to MPP-enabled services. Set up Tempo Wallet or the mppx SDK to handle 402 payment flows automatically.
- [Use with your app](/quickstart/client): Handle payment-gated resources in your app. Use the mppx client SDK to intercept 402 responses, pay, and retry—all automatically.
- [Add payments to your API](/quickstart/server): Add payment-gated access to your API with mppx. Accept stablecoins, cards, and Bitcoin in a few lines of code using the MPP server SDK.
- [SDK features](/sdk/features): Feature parity across TypeScript, Python, and Rust MPP SDKs.
- [Python SDK](/sdk/python/): The pympp Python library
- [Rust SDK for MPP](/sdk/rust/): The mpp Rust library
- [Getting started](/sdk/typescript/): The mppx TypeScript library
- [Card charge](/payment-methods/card/charge): One-time payments using encrypted network tokens
- [Lightning charge](/payment-methods/lightning/charge): One-time payments using BOLT11 invoices
- [Lightning session](/payment-methods/lightning/session): Pay-as-you-go payments over Lightning
- [Solana charge](/payment-methods/solana/charge): One-time payments on Solana
- [Stellar charge](/payment-methods/stellar/charge): One-time SEP-41 token transfers
- [Channel](/payment-methods/stellar/session): High-frequency off-chain payments
- [Stripe charge](/payment-methods/stripe/charge): One-time payments using Shared Payment Tokens
- [Tempo charge](/payment-methods/tempo/charge): One-time TIP-20 token transfers
- [Session](/payment-methods/tempo/session): Low-cost high-throughput payments
- [HTTP transport](/protocol/transports/http): The HTTP transport maps MPP payment flows to standard HTTP headers—WWW-Authenticate for Challenges, Authorization for Credentials, and Payment-Receipt.
- [MCP and JSON-RPC transport](/protocol/transports/mcp): Payment flows for AI tool calls
- [Python MPP client](/sdk/python/client): Handle 402 responses automatically
- [Core Types](/sdk/python/core): Challenge, Credential, and Receipt primitives
- [Server](/sdk/python/server): Protect endpoints with payment requirements
- [Client](/sdk/rust/client): Handle 402 responses automatically
- [Core types](/sdk/rust/core): Challenge, Credential, and Receipt primitives
- [Server](/sdk/rust/server): Protect endpoints with payment requirements
- [CLI Reference](/sdk/typescript/cli): Built-in command-line tool for paid HTTP requests
- [Html.init](/sdk/typescript/Html.init): Build custom payment UIs for browser-based 402 flows
- [Method.from](/sdk/typescript/Method.from): Create a payment method from a definition
- [Paid API proxy server](/sdk/typescript/proxy): Paid API proxy
- [McpClient.wrap](/sdk/typescript/client/McpClient.wrap): Payment-aware MCP client
- [stripe client method](/sdk/typescript/client/Method.stripe): Register all Stripe intents
- [Method.stripe.charge](/sdk/typescript/client/Method.stripe.charge): One-time payments via Shared Payment Tokens
- [tempo client method](/sdk/typescript/client/Method.tempo): Register all Tempo intents
- [Method.tempo.charge](/sdk/typescript/client/Method.tempo.charge): One-time payments
- [Method.tempo.session](/sdk/typescript/client/Method.tempo.session): Low-cost high-throughput payments
- [tempo.session](/sdk/typescript/client/Method.tempo.session-manager): Standalone session manager
- [Mppx.create](/sdk/typescript/client/Mppx.create): Create a payment-aware fetch client
- [Mppx.restore](/sdk/typescript/client/Mppx.restore): Restore the original global fetch
- [Transport.from](/sdk/typescript/client/Transport.from): Create a custom transport
- [Transport.http](/sdk/typescript/client/Transport.http): HTTP transport for payments
- [Transport.mcp](/sdk/typescript/client/Transport.mcp): MCP transport for payments
- [BodyDigest.compute](/sdk/typescript/core/BodyDigest.compute): Compute a body digest hash
- [BodyDigest.verify](/sdk/typescript/core/BodyDigest.verify): Verify a body digest hash
- [Challenge.deserialize](/sdk/typescript/core/Challenge.deserialize): Deserialize a Challenge from a header
- [Challenge.from](/sdk/typescript/core/Challenge.from): Create a new Challenge
- [Challenge.fromHeaders](/sdk/typescript/core/Challenge.fromHeaders): Extract a Challenge from Headers
- [Challenge.fromMethod](/sdk/typescript/core/Challenge.fromMethod): Create a Challenge from a method
- [Challenge.fromResponse](/sdk/typescript/core/Challenge.fromResponse): Extract a Challenge from a Response
- [Challenge.meta](/sdk/typescript/core/Challenge.meta): Extract correlation data from a Challenge
- [Challenge.serialize](/sdk/typescript/core/Challenge.serialize): Serialize a Challenge to a header
- [Challenge.verify](/sdk/typescript/core/Challenge.verify): Verify a Challenge HMAC
- [Credential.deserialize](/sdk/typescript/core/Credential.deserialize): Deserialize a Credential from a header
- [Credential.from](/sdk/typescript/core/Credential.from): Create a new Credential
- [Credential.fromRequest](/sdk/typescript/core/Credential.fromRequest): Extract a Credential from a Request
- [Credential.serialize](/sdk/typescript/core/Credential.serialize): Serialize a Credential to a header
- [Expires utility functions](/sdk/typescript/core/Expires): Generate relative expiration timestamps
- [Method.from](/sdk/typescript/core/Method.from): Create a payment method definition
- [Method.toClient](/sdk/typescript/core/Method.toClient): Extend a method with client logic
- [Method.toServer](/sdk/typescript/core/Method.toServer): Extend a method with server verification
- [PaymentRequest.deserialize](/sdk/typescript/core/PaymentRequest.deserialize): Deserialize a payment request
- [PaymentRequest.from](/sdk/typescript/core/PaymentRequest.from): Create a payment request
- [PaymentRequest.serialize](/sdk/typescript/core/PaymentRequest.serialize): Serialize a payment request to a string
- [Receipt.deserialize](/sdk/typescript/core/Receipt.deserialize): Deserialize a Receipt from a header
- [Receipt.from](/sdk/typescript/core/Receipt.from): Create a new Receipt
- [Receipt.fromResponse](/sdk/typescript/core/Receipt.fromResponse): Extract a Receipt from a Response
- [Receipt.serialize](/sdk/typescript/core/Receipt.serialize): Serialize a Receipt to a string
- [Custom HTML](/sdk/typescript/html/custom): Add payment link support to a custom payment method with Html.init and Method.toServer
- [Elysia payment middleware](/sdk/typescript/middlewares/elysia): Payment middleware for Elysia
- [Express payment middleware](/sdk/typescript/middlewares/express): Payment middleware for Express
- [Hono payment middleware](/sdk/typescript/middlewares/hono): Payment middleware for Hono
- [Next.js payment middleware](/sdk/typescript/middlewares/nextjs): Payment middleware for Next.js
- [stripe](/sdk/typescript/server/Method.stripe): Register all Stripe intents
- [Method.stripe.charge](/sdk/typescript/server/Method.stripe.charge): One-time payments via Shared Payment Tokens
- [tempo server method](/sdk/typescript/server/Method.tempo): Register all Tempo intents
- [Method.tempo.charge](/sdk/typescript/server/Method.tempo.charge): One-time stablecoin payments
- [Method.tempo.session](/sdk/typescript/server/Method.tempo.session): Low-cost high-throughput payments
- [Mppx.compose](/sdk/typescript/server/Mppx.compose): Present multiple payment options
- [Mppx.create](/sdk/typescript/server/Mppx.create): Create a server-side payment handler
- [Mppx.toNodeListener](/sdk/typescript/server/Mppx.toNodeListener): Adapt payments for Node.js HTTP
- [Request.toNodeListener](/sdk/typescript/server/Request.toNodeListener): Convert Fetch handlers to Node.js
- [Response.requirePayment](/sdk/typescript/server/Response.requirePayment): Create a 402 response
- [Transport.from](/sdk/typescript/server/Transport.from): Create a custom transport
- [Transport.http](/sdk/typescript/server/Transport.http): HTTP server-side transport
- [Transport.mcp](/sdk/typescript/server/Transport.mcp): Raw JSON-RPC MCP transport
- [Transport.mcpSdk](/sdk/typescript/server/Transport.mcpSdk): MCP SDK server-side transport
-->

# `Html.init` \[Initialize a payment UI context]

Sets up a context for building payment method UIs in the browser. Returns challenge data, theme tokens, and helpers for error handling and credential submission.

For a full guide on adding HTML support to a custom payment method, see [Custom HTML](/sdk/typescript/html/custom).

## Usage

```ts [example.ts]
import * as Html from 'mppx/html'

const context = Html.init('tempo')

// Mount your UI
const button = document.createElement('button')
button.textContent = context.text.pay
context.root.appendChild(button)
```

### With credential submission

Build a complete payment form that handles errors and submits credentials.

```ts [example.ts]
import * as Html from 'mppx/html'

const c = Html.init('tempo')

const button = document.createElement('button')
button.textContent = c.text.pay
button.onclick = async () => {
  try {
    c.error()
    button.disabled = true
    const credential = await method.createCredential({
      challenge: c.challenge,
      context: {},
    })
    await c.submit(credential)
  } catch (e) {
    c.error(e instanceof Error ? e.message : 'Payment failed')
  } finally {
    button.disabled = false
  }
}
c.root.appendChild(button)
```

### With CSS theming

Use `context.vars` for CSS custom property references that respect the server-configured theme.

```ts [example.ts]
import * as Html from 'mppx/html'

const c = Html.init('tempo')

const style = document.createElement('style')
style.textContent = `
  button {
    background: ${c.vars.accent};
    border-radius: ${c.vars.radius};
    color: ${c.vars.background};
    font-family: ${c.vars.fontFamily};
    padding: calc(${c.vars.spacingUnit} * 4) calc(${c.vars.spacingUnit} * 8);
  }
`
c.root.appendChild(style)
```

## Return type

```ts
type Context = {
  /** The parsed Challenge object for this payment method. */
  challenge: Challenge
  /** Handler-specific HTML configuration. */
  config: Record<string, unknown>
  /** Show or clear an error message below the root element. */
  error: (message?: string | null | undefined) => void
  /** Pre-formatted amount string (for example, "$10.00"). */
  formattedAmount: string
  /** Human-readable payment method label. */
  label: string
  /** The DOM element to mount your payment UI into. */
  root: HTMLElement
  /** Submit a credential and reload the page. */
  submit: (credential: string) => Promise<void>
  /** UI text strings with defaults applied. */
  text: { expires: string; pay: string; paymentRequired: string; title: string }
  /** Resolved theme tokens (colors, spacing, typography). */
  theme: Record<string, string>
  /** CSS custom property references for theming. */
  vars: {
    accent: CssVar       // var(--mppx-accent)
    background: CssVar   // var(--mppx-background)
    border: CssVar       // var(--mppx-border)
    fontFamily: CssVar   // var(--mppx-font-family)
    fontSizeBase: CssVar // var(--mppx-font-size-base)
    foreground: CssVar   // var(--mppx-foreground)
    muted: CssVar        // var(--mppx-muted)
    negative: CssVar     // var(--mppx-negative)
    positive: CssVar     // var(--mppx-positive)
    radius: CssVar       // var(--mppx-radius)
    spacingUnit: CssVar  // var(--mppx-spacing-unit)
    surface: CssVar      // var(--mppx-surface)
  }
}
```

## Parameters

### methodName

* **Type:** `string`

The payment method name to initialize (for example, `'tempo'`, `'stripe'`). Matches against the challenge data the server embeds in the page.

## Context properties

### challenge

* **Type:** `Challenge`

The parsed Challenge object for this payment method. Contains `intent`, `method`, `realm`, `request`, and other challenge fields.

### config

* **Type:** `Record<string, unknown>`

Method-specific configuration provided by the server. For example, Stripe passes `{ publishableKey: string }`.

### error

* **Type:** `(message?: string | null | undefined) => void`

Shows or clears an error message. Pass a string to display an error below the root element. Call with no arguments (or `null`/`undefined`) to clear the error.

### formattedAmount

* **Type:** `string`

Pre-formatted amount string from the server (for example, `"$10.00"`).

### label

* **Type:** `string`

Payment method label, used for tab labels when multiple methods are available.

### root

* **Type:** `HTMLElement`

The DOM element to mount your payment UI into. Append your form elements here.

### submit

* **Type:** `(credential: string) => Promise<void>`

Sends the credential to the server via a Service Worker, then reloads the page. Call after creating a credential from the challenge.

### text

* **Type:** `{ expires: string; pay: string; paymentRequired: string; title: string }`

UI text strings with defaults applied.

| Key | Default |
|---|---|
| `expires` | `"Expires at"` |
| `pay` | `"Pay"` |
| `paymentRequired` | `"Payment Required"` |
| `title` | `"Payment Required"` |

### theme

* **Type:** `Record<string, string>`

Resolved theme tokens with defaults applied. Includes color tokens (`accent`, `background`, `border`, `foreground`, `muted`, `negative`, `positive`, `surface`) and layout tokens (`colorScheme`, `fontFamily`, `fontSizeBase`, `radius`, `spacingUnit`).

### vars

* **Type:** `typeof vars`

CSS custom property references for use in inline styles or `<style>` blocks. Each property returns the corresponding `var(--mppx-*)` value when used in a string.

| Property | CSS variable |
|---|---|
| `accent` | `var(--mppx-accent)` |
| `background` | `var(--mppx-background)` |
| `border` | `var(--mppx-border)` |
| `fontFamily` | `var(--mppx-font-family)` |
| `fontSizeBase` | `var(--mppx-font-size-base)` |
| `foreground` | `var(--mppx-foreground)` |
| `muted` | `var(--mppx-muted)` |
| `negative` | `var(--mppx-negative)` |
| `positive` | `var(--mppx-positive)` |
| `radius` | `var(--mppx-radius)` |
| `spacingUnit` | `var(--mppx-spacing-unit)` |
| `surface` | `var(--mppx-surface)` |