MPP.AcceptPayment (mpp v0.20.1)

Parse, format, and rank the Accept-Payment client-preference header.

The Accept-Payment header lets a client advertise which method/intent pairs it can pay with, optionally weighted by an RFC 9110 qvalue (0/1 with up to three fraction digits), so a server can filter and reorder its offers to match. The syntax mirrors HTTP content negotiation: method/intent[;q=value], comma-separated. The q parameter name is case-insensitive (Q=0 is an opt-out).

# Client: build a preference header
MPP.AcceptPayment.format([{"stripe", "charge", 1.0}, {"tempo", "charge", 0.5}])
# → "stripe/charge, tempo/charge;q=0.5"

# Server: parse a request header
MPP.AcceptPayment.parse("stripe/charge, tempo/charge;q=0.5")
# → [{"stripe", "charge", 1.0}, {"tempo", "charge", 0.5}]

# Server: reorder offers by client preference
MPP.AcceptPayment.apply_header(offers, header, &offer_method_intent/1)

Malformed input is ignored (returns [] or a no-op) per the spec's MAY-ignore rule; oversized headers (> 16 KiB) are ignored the same way as a DoS guard.

API Functions

Function	Arity	Description	Param Kinds
`rank`	3	Reorder server offers by client `Accept-Payment` preferences. Excludes `q=0` matches.	`offers: value`, `preferences: value`, `method_intent: value`
`format`	1	Format preference entries into an `Accept-Payment` header value.	`entries: value`
`apply_header`	3	Filter and reorder server offers using a request `Accept-Payment` header. Malformed or no-match headers are a no-op.	`offers: value`, `header: value`, `method_intent: value`
`parse`	1	Parse an `Accept-Payment` header into client preference entries. Malformed input returns `[]` (spec MAY-ignore).	`header: value`

Summary

Types

entry()

Functions

apply_header(offers, header, method_intent)

Filter and reorder server offers using an Accept-Payment header.

format(entries)

Format preference entries into an Accept-Payment header value.

parse(header)

Parse an Accept-Payment header value into preference entries.

rank(offers, preferences, method_intent \\ &default_method_intent/1)

Reorder server offers by client Accept-Payment preferences.

Types

entry()

@type entry() :: {String.t(), String.t(), float()}

Functions

apply_header(offers, header, method_intent)

@spec apply_header([term()], String.t() | nil, (term() -> {String.t(), String.t()})) ::
  [term()]

Filter and reorder server offers using an Accept-Payment header.

Returns offers unchanged when header is nil, malformed, oversized (> 16 KiB), or matches no offers (spec MAY-ignore).

format(entries)

@spec format([entry() | map()]) :: String.t()

Format preference entries into an Accept-Payment header value.

Omits ;q= when q is 1.0. Entries may be {method, intent, q} tuples or maps with :method, :intent, and :q keys.

parse(header)

@spec parse(String.t()) :: [entry()]

Parse an Accept-Payment header value into preference entries.

Each entry is {method, intent, q} where method is * or a challenge method name ([a-z][a-z0-9:_-]*), intent is * or [a-z0-9-]+, and q is an RFC 9110 qvalue (default 1.0).

Returns [] for empty, whitespace-only, or malformed input (spec MAY-ignore). Headers larger than 16 KiB are ignored the same way (DoS cap, applied before parsing).

rank(offers, preferences, method_intent \\ &default_method_intent/1)

@spec rank([term()], [entry() | map()], (term() -> {String.t(), String.t()})) :: [
  term()
]

Reorder server offers by client Accept-Payment preferences.

Offers with no matching preference or only q=0 matches are excluded. Sorting matches mpp-rs / mppx: highest effective q, then original offer order.

method_intent extracts {method, intent} from each offer (defaults to challenge fields when omitted).