> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://mpp.dev/api/mcp` to find what you need.

# Protocol overview \[Standardizing HTTP 402 for machine-to-machine payments]

The Machine Payments Protocol (MPP) is a protocol for machine-to-machine payments. It standardizes HTTP `402` "Payment Required" with an extensible framework that works with any payment network.

These docs provide a developer-friendly overview. For the full specification, see the full [IETF Specification](https://paymentauth.org).

## Flow

```mermaid
sequenceDiagram
  participant Client
  participant Server
  Client->>Server: GET /resource
  Server-->>Client: 402 Payment Required + Challenge
  Client->>Server: GET /resource + Credential
  Server-->>Client: 200 OK + Receipt
```

1. Request the resource.
2. Receive a 402 Challenge.
3. Fulfill the payment and retry with a Credential.
4. Receive the resource and Receipt.

## Core concepts

[HTTP 402](/protocol/http-402) — The 402 status code that signals payment is required

[Challenges](/protocol/challenges) — Server-issued payment requirements in WWW-Authenticate

[Credentials](/protocol/credentials) — Client-submitted payment proofs in Authorization

[Receipts](/protocol/receipts) — Server acknowledgment of successful payment

[Transports](/protocol/transports) — HTTP and MCP transport bindings

## Status codes

MPP uses HTTP status codes consistently to signal payment-related conditions:

:::info[Consistent 402 usage]
MPP uses `402` for all payment-related Challenges, including failed Credential validation. This differs from other HTTP authentication schemes that use `401` for failed Credentials. The distinction:

* **`402`** = Payment barrier (initial Challenge or retry needed)
* **`401`** = Authentication failure unrelated to payment
* **`403`** = Payment succeeded but access denied by policy
:::

| Condition                                          | Status                               | Response                                         |
| -------------------------------------------------- | ------------------------------------ | ------------------------------------------------ |
| Resource requires payment, no Credential provided  | 402  | Fresh Challenge in `WWW-Authenticate`            |
| Malformed Credential (invalid base64url, bad JSON) | 402  | Fresh Challenge + `malformed-credential` problem |
| Unknown, expired, or already-used Challenge id     | 402  | Fresh Challenge + `invalid-challenge` problem    |
| Payment proof invalid or verification failed       | 402  | Fresh Challenge + `verification-failed` problem  |
| Payment verified, access granted                   | 200 | Resource + optional `Payment-Receipt`            |
| Payment verified, but policy denies access         | 403 | No Challenge (payment was valid)                 |

See [HTTP 402](/protocol/http-402) for details on when to return each status code.

## Payment method agnostic

MPP works with any payment network or currency. The core protocol defines the framework, while **payment methods** define how specific networks integrate:

:::info[Extensible by design]
Anyone can define new payment methods. The protocol requires that methods define their `request` schema (what the server asks for) and `payload` schema (what the client provides as proof).
:::

| Method                            | Description                                     | Status                                      |
| --------------------------------- | ----------------------------------------------- | ------------------------------------------- |
| [Tempo](/payment-methods/tempo)   | Native stablecoin payments on Tempo Network     | Production |
| [Stripe](/payment-methods/stripe) | Traditional card payment methods through Stripe | Production |

Each payment method specifies its own `request` and `payload` schemas while sharing the common Challenge/Credential flow.

### Payment method requirements

Payment method specifications must define:

1. **Method identifier**—Unique lowercase ASCII string (for example, `tempo` or `stripe`)
2. **Request schema**—JSON structure for the `request` parameter in Challenges
3. **Payload schema**—JSON structure for Credential `payload` fields
4. **Verification procedure**—How servers validate payment proofs
5. **Settlement procedure**—How payment is finalized

## Payment intents

Payment intents describe the type of payment being requested. Common intents include:

* **`charge`**—One-time payment that settles immediately
* **`session`**—Streaming payment over a payment channel
* **`subscription`**—Recurring fixed payment for paid access across billing periods

Intent definitions in the IETF Specification define:

* Required and optional `request` fields
* `payload` requirements
* Verification and settlement semantics

Servers can offer multiple intents in separate Challenges, allowing clients to choose:

```http
WWW-Authenticate: Payment id="abc", method="tempo", intent="charge", ...
WWW-Authenticate: Payment id="def", method="tempo", intent="session", ...
WWW-Authenticate: Payment id="ghi", method="tempo", intent="subscription", ...
```

## Request body binding

For requests with bodies (`POST`, `PUT`, `PATCH`), servers can bind the Challenge to the request body using a `digest` parameter:

```http
WWW-Authenticate: Payment id="...",
    method="tempo",
    intent="charge",
    digest="sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:",
    request="..."
```

When a `digest` is present, clients must submit the Credential with a request body whose digest matches. This prevents clients from modifying the request body after receiving the Challenge.

The digest is computed per [RFC 9530](https://www.rfc-editor.org/rfc/rfc9530) Content-Digest header format.

## Error handling

Failed payment attempts return `402` with a fresh Challenge and a Problem Details [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) body:

```json
{
  "type": "https://paymentauth.org/problems/verification-failed",
  "title": "Payment Verification Failed",
  "status": 402,
  "detail": "Invalid payment proof."
}
```

Common error codes (full type URI: `https://paymentauth.org/problems/{code}`):

| Code                   | Description                                    |
| ---------------------- | ---------------------------------------------- |
| `payment-required`     | Resource requires payment                      |
| `payment-insufficient` | Amount too low                                 |
| `payment-expired`      | Challenge or authorization expired             |
| `verification-failed`  | Proof invalid                                  |
| `method-unsupported`   | Method not accepted                            |
| `malformed-credential` | Invalid Credential format                      |
| `invalid-challenge`    | Challenge ID unknown, expired, or already used |

Use the `Retry-After` header to indicate when clients can retry failed payments.

## Security considerations

### Transport security

**TLS 1.2 or later is REQUIRED** for all Payment authentication flows. Use TLS 1.3 where possible. Payment Credentials contain sensitive authorization data that could result in financial loss if intercepted.

### Replay protection

Payment methods must provide single-use proof semantics. A payment proof can be used exactly once; subsequent attempts to use the same proof must be rejected.

### Idempotency

Servers must not perform side effects (database writes, external API calls) for requests that have not been paid. The unpaid request that triggers a `402` Challenge must not modify server state beyond recording the Challenge itself.

For non-idempotent methods (`POST`, `PUT`, `DELETE`), accept an `Idempotency-Key` header to enable safe client retries.

### Amount verification

Clients must verify before authorizing payment:

1. Requested amount is reasonable for the resource
2. Recipient/address is expected
3. Currency/asset is as expected
4. Validity window is appropriate

:::warning[Don't trust descriptions]
Clients must not rely on the `description` parameter for payment verification. Malicious servers could provide a misleading description while the actual `request` payload requests a different amount.
:::

### Credential handling

Payment Credentials are bearer tokens that authorize financial transactions. Servers and intermediaries must not log Payment Credentials or include them in error messages, debugging output, or analytics.

### Caching

Payment Challenges contain unique identifiers and time-sensitive payment data that must not be cached. Servers must send `Cache-Control: no-store` with `402` responses. Responses containing `Payment-Receipt` headers must include `Cache-Control: private`.

## Extensibility

The protocol is designed for extensibility, with simple constraints where required for security or a consistent developer experience:

### Custom parameters

Implementations may define additional parameters in Challenges:

* Parameters must use lowercase names
* Unknown parameters must be ignored by clients
* This allows payment methods to add method-specific fields

### Size considerations

* Keep Challenges under 8 KB
* Clients must handle Challenges of at least 4 KB
* Servers must handle Credentials of at least 4 KB

### Internationalization

* All string values use UTF-8 encoding
* Payment method identifiers are restricted to ASCII lowercase
* Use ASCII-only values for the `realm` parameter
* The `description` parameter can contain localized text; use `Accept-Language` to determine appropriate language

## Full specification

These docs provide a practical overview. For the full specification:

[Payment HTTP Authentication Scheme](https://paymentauth.org/draft-httpauth-payment-00) — Core protocol spec (draft-httpauth-payment-00)

[MCP Transport](https://paymentauth.org/draft-payment-transport-mcp-00) — Model Context Protocol binding

[Payment Methods and Intents](https://paymentauth.org) — Method and intent definitions (charge, session, subscription)

[IETF Specification](https://paymentauth.org) — Browse the full specification directory

The full specification includes detailed ABNF grammar, security analysis, IANA considerations, and complete examples for various payment scenarios.