HTTP 402 payment required

MPP services return HTTP 402 Payment Required to indicate that a resource requires payment for access.

Overview

Respond with 402 when:

• A resource requires payment as a precondition for access
• The server can provide a Payment challenge the client can fulfill
• Payment is the primary barrier (not authentication or authorization, which would result in a 401 and then potentially an incremental 402)

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="abc123",
    realm="mpp.dev",
    method="tempo",
    intent="charge",
    request="eyJ..."

Status code comparison

MPP uses 402 consistently for all payment-related challenges, including when a credential fails validation. This differs from other HTTP authentication schemes that use 401 for failed credentials.

Token authentication

When a resource requires both token and payment authentication:

1. Verify authentication credentials
2. Return 401 if token authentication fails
3. Return 402 with a Payment challenge only after successful token authentication

This ordering prevents leaking payment requirements to unauthenticated clients.

Error responses

Failed payment attempts return 402 with a fresh challenge and a Problem Details body:

HTTP/1.1 402 Payment Required
Cache-Control: no-store
Content-Type: application/problem+json
WWW-Authenticate: Payment id="new456", ...
 
{
  "type": "https://paymentauth.org/problems/verification-failed",
  "title": "Payment Verification Failed",
  "status": 402,
  "detail": "Invalid payment proof."
}

Error types include:

• invalid-challenge—Unknown, expired, or already-used challenge
• malformed-credential—Invalid base64url or bad JSON
• method-unsupported—Method not accepted (400)
• payment-expired—Challenge or authorization expired
• payment-insufficient—Amount too low
• payment-required—Resource requires payment
• verification-failed—Payment proof invalid

Learn more