> ## Documentation Index
> Fetch the complete documentation index at: https://docs.madra.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP 402 Payment Required

> How the reserved 402 status code is used as a machine-readable payment challenge in x402.

HTTP 402 is the status code every browser has known about and nobody has ever seen. It was reserved in the original HTTP spec as "Payment Required" and left without a defined body, waiting for someone to give it a wire format. x402 is that wire format.

## The exchange, minimally

1. Client requests a resource with no proof of payment.
2. Server responds `402 Payment Required` with a `PaymentRequired` header describing what is owed.
3. Client reads the header, signs a payment authorization, and retries with an `X-Payment` header.
4. Server hands the payload to a facilitator to verify (and later settle) the payment.
5. Server returns the resource.

That is the whole protocol. Everything else in these docs, schemes, discovery, MCP tools, is refinement on top of it.

## The 402 response

```http theme={null}
HTTP/1.1 402 Payment Required
Content-Type: application/json
PaymentRequired: <base64-encoded PaymentRequirements JSON>
```

The `PaymentRequired` header is a base64-encoded JSON object. Its full schema is documented in the [API reference](/api/verify), but the fields you care about are:

| Field               | Meaning                                                        |
| ------------------- | -------------------------------------------------------------- |
| `scheme`            | Which payment scheme applies (`exact`, `upto`).                |
| `network`           | Which network to pay on (`stellar:testnet`, `stellar:pubnet`). |
| `amount`            | Price in the smallest unit of `asset`.                         |
| `asset`             | The SEP-41 token address and decimals.                         |
| `payTo`             | The seller's Stellar account.                                  |
| `maxTimeoutSeconds` | How long the client has to sign and re-send.                   |

## The retry

```http theme={null}
GET /resource HTTP/1.1
X-Payment: <base64-encoded PaymentPayload JSON>
```

The `X-Payment` payload carries the signed authorization entries and identifies the client. See [PaymentPayload](/api/verify).

## What 402 is not

* **Not authentication.** A 402 says "you have not paid," not "we do not know who you are." It is compatible with API keys and OAuth, but does not replace them.
* **Not rate limiting.** Rate limits use 429. If your server wants to slow a paid caller down, return 429, not 402.
* **Not a redirect.** The client is expected to retry the same request against the same URL with an `X-Payment` header, not follow a `Location`.

## Where next

* [Client / Facilitator / Server](/concepts/client-facilitator-server) explains who does what in the exchange.
* [Payment Schemes](/payment-schemes/overview) covers `exact` and `upto`.
* [Error & Rejection Codes](/reference/error-codes) is where you go when a 402 (or a subsequent verify) rejects a payment for a reason you have not seen before.