technical

HTTP 402 for APIs: request, challenge, and record

HTTP 402 Payment Required was reserved in 1999 for "future digital payments." That future is now. Here is how to implement 402 responses that work for automated agents and human developers alike.
Jithin Raj, Founder2 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 provides semantic clarity. 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."
  }
}

Receipt verification: the critical step

A receipt is cryptographic proof 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 is just the transport layer. 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