Paymentauth Integration
Parse HTTP Payment authentication challenges and receipts into verifiable PEAC records. The package provides envelope-first parsing that preserves raw upstream artifacts and coexists with the PEAC-Receipt header.
Package: @peac/mappings-paymentauth
What It Does
The paymentauth mapping parses HTTP 402 flows that use the Payment authentication scheme (draft-ryan-httpauth-payment). It extracts Challenge, Credential, and Receipt envelopes, preserving both the raw header value and a normalized payload.
1. Server issues a 402 challenge
The server returns WWW-Authenticate: Payment with method-specific parameters. The parser extracts the challenge envelope with scheme, realm, and method payload.
2. Client responds with credentials
The client sends Authorization: Payment with the payment credential. The parser extracts the credential envelope with the raw method payload preserved as unknown (version-agnostic).
3. Server returns a payment receipt
The server responds with Payment-Receipt containing the upstream receipt. The carrier adapter extracts this alongside the PEAC-Receipt header, maintaining coexistence without conflict.
Install
pnpm add @peac/mappings-paymentauth
Envelope Types
The parser produces three envelope types, each preserving the raw header value alongside the normalized payload:
| Envelope | HTTP Header | Description |
|---|---|---|
Challenge | WWW-Authenticate: Payment | Server-issued 402 challenge with method parameters |
Credential | Authorization: Payment | Client payment credential with method payload |
Receipt | Payment-Receipt | Server-issued upstream payment receipt |
Carrier Coexistence
HTTP responses may carry both a PEAC-Receipt header (PEAC compact JWS) and a Payment-Receipt header (upstream payment receipt). The carrier adapter reads both without conflict:
PEAC-Receiptcontains the signed PEAC interaction record (compact JWS)Payment-Receiptcontains the upstream payment receipt (raw, preserved as-is)receipt_refcomputed assha256(raw_header_value)
Usage Example
import { parseChallenge, parseReceipt } from '@peac/mappings-paymentauth';
import { fromPaymentauthReceipt } from '@peac/mappings-paymentauth/map';
// Parse a 402 challenge from WWW-Authenticate header
const challenge = parseChallenge(wwwAuthenticateHeader);
// { scheme: 'Payment', realm: '...', method: '...', raw: '...' }
// Parse the upstream receipt from Payment-Receipt header
const receipt = parseReceipt(paymentReceiptHeader);
// { raw: '...', normalized: { ... } }
// Map into PEAC evidence
const evidence = fromPaymentauthReceipt(receipt, {
iss: 'https://gateway.example.com',
aud: 'client.example.com',
});JSON-RPC and MCP Support
The package includes helpers for paymentauth errors in JSON-RPC and MCP transports:
| Error Code | Transport | Description |
|---|---|---|
-32042 | JSON-RPC | Payment required (challenge issued) |
-32043 | JSON-RPC | Payment failed (credential rejected) |
MCP-specific extraction functions are available for reading paymentauth artifacts from MCP tool response metadata.
Semantic Boundary
PEAC is the evidence layer: it records what happened, never executes payments, coordinates checkout, or manages wallets. The paymentauth mapping preserves raw upstream artifacts and does not synthesize payment finality. A paymentauth receipt proves what the upstream server attested, not more.
Links
Portable Commerce Evidence
Receipts from paymentauth flows are portable across all PEAC transports. The same receipt can travel through MCP, A2A, ACP, UCP, x402, and HTTP. A verifier needs only the issuer's public key to confirm the payment evidence.