HTTP transport

Payment flows using standard HTTP headers

The HTTP transport is the primary binding for MPP, using standard HTTP headers from RFC 9110.

Headers

Direction	Header	Purpose
Server → Client	`WWW-Authenticate: Payment ...`	Challenge
Client → Server	`Authorization: Payment ...`	Credential when the Challenge omits `header`
Client → Server	`Payment-Authorization: Payment ...`	Credential when the Challenge sets `header="Payment-Authorization"`
Server → Client	`Payment-Receipt: ...`	Receipt

Example flow

Client
Request a resource

GET /api/data HTTP/1.1
Host: api.example.com

Server
Send a payment Challenge

Return the WWW-Authenticate header with a Payment Challenge.

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

Client
Retry with a Credential

Send the Authorization header.

GET /api/data HTTP/1.1
Host: api.example.com
Authorization: Payment eyJjaGFsbGVuZ2UiOnsiaWQiOiJhYmMxMjMi...

Server
Return a Receipt

Return the Payment-Receipt header with a success Receipt.

HTTP/1.1 200 OK
Payment-Receipt: eyJzdGF0dXMiOiJzdWNjZXNzIi4uLn0
Content-Type: application/json
 
{"data": "..."}

Header encoding

Challenges are encoded as auth-params in WWW-Authenticate. The request and opaque auth-params use base64url-encoded JCS JSON strings. Credentials echo those same Challenge values inside the base64url-encoded Payment Credential, and Receipts use base64url-encoded JSON in Payment-Receipt.

Combine application authentication and payment

Use a separate payment field when your endpoint needs a Bearer, Basic, or other application Credential in Authorization. With mppx, set requiresAuth: true on the server. The Challenge advertises header="Payment-Authorization", and compatible clients attach the Payment Credential there without replacing the existing Authorization value.

GET /api/data HTTP/1.1
Authorization: Bearer application-token
Host: api.example.com
Payment-Authorization: Payment eyJjaGFsbGVuZ2UiOnsiaWQiOiJhYmMxMjMi...

Full specification

IETF Specification

Read the full specification

Suggest changes to this page