Skip to main content
TECHNICAL

HTTP 402 for APIs: Making Payment-Required Responses Work

HTTP 402 Payment Required was reserved in 1999 for “future digital payments.” That future is now. Here’s how to implement 402 responses that work for automated agents and human developers alike.

By Jithin Raj & Originary Team••12 min read

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 >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 machine-readable JSON hint
  • ✅ Include reference field mapped to 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’s next

HTTP 402 is just the transport layer. To build a complete agent-to-agent commerce system, you’ll need receipt issuance, entitlement tracking, monitoring, and client SDKs.

For step-by-step implementation guides with Express, Next.js, and Cloudflare Workers, see our x402 integration documentation.

Related Reading

Ready to implement HTTP 402?

Learn how Originary helps build production HTTP 402 flows with receipts, verification, and agent-native commerce.