technical

HTTP 402 for APIs: request, challenge, and record

HTTP 402 Payment Required was reserved in 1997 (RFC 2068) for "future digital payments." Agents calling priced APIs now give it a use. This is how to build 402 responses that both automated agents and human developers can act on.
Originary2 min read
Archived. This piece reflects earlier work and uses legacy terminology and commands. It is kept for the record and is not maintained against the current release. See the current writing for up-to-date guidance.

Why 402 matters for APIs

Modern APIs serve both humans and agents. When an agent hits a priced endpoint, it needs:

  • Programmatic discovery. Know what to pay without parsing HTML.
  • Rail flexibility. Use any payment method that provides a receipt.
  • Automatic retry. Present receipt and get resource in one flow.
  • Clear semantics. Distinguish payment from auth/permission issues.

HTTP 402 has a distinct meaning. Unlike 401 (auth missing) or 403 (permission denied), 402 signals: "This resource exists, pay first."

Anatomy of a working 402 response

A minimal 402 response includes four key elements:

  1. Status code: 402
  2. Human-readable detail: why payment is required
  3. Machine-readable hint: protocol, amount, currency, reference
  4. Instructions: how to pay and retry
HTTP/1.1 402 Payment Required
Content-Type: application/json
Cache-Control: no-store

{
  "detail": "Payment required to access this resource.",
  "payment": {
    "protocol": "x402",
    "amount": "0.50",
    "currency": "USD",
    "reference": "invoice-abc-789",
    "instructions": "Pay and include receipt in X-Receipt header on retry."
  }
}

Verifying the receipt

A receipt is signed evidence of payment. Your server must verify four things:

  1. Verify signature. Ensure receipt is from a trusted source using cryptographic verification.
  2. Check timestamp. Reject expired receipts (typically more than 5 minutes old).
  3. Match reference. Confirm receipt corresponds to the original challenge.
  4. Prevent replay. Track used receipts and reject duplicates.

Real-world implementation checklist

  • Return 402 with a machine-readable JSON hint
  • Include a reference field mapped to your entitlement ledger
  • Set Cache-Control: no-store
  • Verify receipt signature, timestamp, reference, replay
  • Return deterministic error codes for invalid receipts
  • Centralize challenge creation in middleware
  • Log challenges and verifications for audit trails
  • Support multiple payment rails (rail-agnostic)

What is next

HTTP 402 only carries the payment signal. To build a complete agent-to-agent commerce system, you will need receipt issuance, entitlement tracking, monitoring, and client SDKs.

See the PEAC Protocol overview for the verifiable interaction-record format used by Originary, and the Downloads page for CLI and SDK packages.

related