# Overview

stripe402 uses the HTTP 402 status code — reserved since 1997 but never standardized — to create a machine-readable payment negotiation between client and server.

## The Flow

```
Client                                          Server
  |                                                |
  |  1. GET /api/weather                           |
  |----------------------------------------------->|
  |                                                |
  |  2. 402 Payment Required                       |
  |  payment-required: <base64 JSON>               |
  |  (price, currency, min top-up, Stripe pub key) |
  |<-----------------------------------------------|
  |                                                |
  |  3. GET /api/weather                           |
  |  payment: <base64 JSON>                        |
  |  (PaymentMethod ID, top-up amount)             |
  |----------------------------------------------->|
  |                                                |
  |  Server charges card via Stripe                |
  |  Server credits balance                        |
  |  Server deducts for this request               |
  |                                                |
  |  4. 200 OK                                     |
  |  payment-response: <base64 JSON>               |
  |  (client ID, remaining credits, charge ID)     |
  |<-----------------------------------------------|
  |                                                |
  |  5. GET /api/weather                           |
  |  payment: <base64 JSON with client ID>         |
  |----------------------------------------------->|
  |                                                |
  |  Server deducts from balance                   |
  |                                                |
  |  6. 200 OK                                     |
  |  payment-response: <base64 JSON>               |
  |<-----------------------------------------------|
```

## Key Concepts

### No Signup Required

The payment **is** the authentication. A client's identity is derived deterministically from their card fingerprint via HMAC-SHA256. Same card, same server, same identity — every time. No passwords, no email, no registration.

### Credits System

Stripe charges a minimum of $0.50 with a \~$0.30 fixed fee per transaction. True per-request micropayments are uneconomical. stripe402 solves this with a credits system: clients top up once (e.g., $5.00 = 50,000 units), then make hundreds of requests against that balance. See [Credits Model](/protocol/credits-model.md).

### Protocol Version

The current protocol version is `1` (constant: `STRIPE402_VERSION`). Both client and server include this in their headers for forward compatibility.

## Topics

* [HTTP Headers](/protocol/http-headers.md) — the three headers and their JSON schemas
* [Payment Flow](/protocol/payment-flow.md) — detailed walkthrough of all code paths
* [Pricing Units](/protocol/pricing-units.md) — the unit system and conversions
* [Client Identity](/protocol/client-identity.md) — HMAC-SHA256 derivation
* [Credits Model](/protocol/credits-model.md) — why credits, how top-ups work
* [Error Codes](/protocol/error-codes.md) — all error codes and when they occur
* [Comparison: stripe402 vs x402](/protocol/comparison-x402.md) — trade-offs between the two approaches


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stripe402.com/protocol/protocol.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.