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

# HTTP 402 Payment Required \[The status code for payments on the web]

MPP services return HTTP `402` Payment Required to indicate that a resource requires payment for access. This is the foundation that enables [API monetization](/use-cases/api-monetization) and [micropayments](/use-cases/micropayments) at the protocol level.

## Overview

Respond with `402` when:

* A resource requires payment as a precondition for access
* The server can provide a `Payment` Challenge the client can fulfill
* Payment is the primary barrier (not authentication or authorization, which would result in a `401` and then potentially an incremental `402`)

```http
HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="abc123",
    realm="mpp.dev",
    method="tempo",
    intent="charge",
    request="eyJ..."
```

## Status code comparison

| Condition | Status Code |
|-----------|-------------|
| Resource requires payment | **`402`** |
| Client lacks authentication | `401` |
| Client authenticated but unauthorized | `403` |
| Resource doesn't exist | `404` |

MPP uses `402` consistently for all payment-related Challenges, including when a Credential fails validation. This differs from other HTTP authentication schemes that use `401` for failed Credentials.

## Token authentication

When a resource requires both **token** and **payment** authentication:

1. Verify authentication credentials
2. Return `401` if token authentication fails
3. Return `402` with a `Payment` Challenge only after successful token authentication

This ordering prevents leaking payment requirements to unauthenticated clients.

:::info
Store authentication tokens in an [HTTP-only cookie](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html#httponly-attribute) to prevent them from conflicting with the payment `Authorization` header and to avoid exposing the token to the client.
:::

## Error responses

Failed payment attempts return `402` with a fresh Challenge and a Problem Details body:

```http
HTTP/1.1 402 Payment Required
Cache-Control: no-store
Content-Type: application/problem+json
WWW-Authenticate: Payment id="new456", ...

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

Error types include:

* `invalid-challenge`—Unknown, expired, or already-used Challenge
* `malformed-credential`—Invalid base64url or bad JSON
* `method-unsupported`—Method not accepted (400)
* `payment-expired`—Challenge or authorization expired
* `payment-insufficient`—Amount too low
* `payment-required`—Resource requires payment
* `verification-failed`—Payment proof invalid

## Learn more

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