Copyright © 2026 the Contributors to the Web Monetization Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA) . A human-readable summary is available.
Web Monetization allows websites to automatically receive payments from users, facilitated by the user agent and a user's preferred monetization provider.
This specification was published by the Web Platform Incubator Community Group . It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups .
This specification is a work in progress within the community on the best shape it should take. Please see the documentation for more info.
The specification reflects the desired end-state of the Web Monetization APIs as currently anticipated and agreed to between the contributors. The specification is being prepared here, in this format, to collect the input of the Web community and prepare the work to ultimately follow the W3C standards track should it have the necessary support to do so.
For the most accurate reflection of the APIs that have been implemented by providers see the API documentation .
GitHub Issues are preferred for discussion of this specification.
This section is non-normative.
Call
supports
()
on
a
link
element’s
relList
passing
the
"monetization"
keyword
to
check
if
Web
Monetization
is
supported
by
the
user
agent.
The
MonetizationEvent
DOM
events
provide
information
such
as
the
amount
sent,
the
currency
of
the
payment,
and
a
link
to
the
incoming
payment
at
the
monetization
receiver
which
can
be
used
to
verify
the
receipt
of
payment.
As
in
the
previous
example
above,
these
events
are
dispatched
to
link
elements
and
bubble
up
the
DOM
tree.
To
listen
for
MonetizationEvent
events,
an
event
listener
needs
to
be
added
to
the
relevant
link
element
(or
to
one
of
its
ancestors)
via
JavaScript:
The
MonetizationEvent
's
incomingPayment
attribute
is
a
URL
that
can
be
used
to
verify
the
payment
at
the
monetization
receiver
.
In
most
cases
requests
to
the
incomingPayment
URL
will
need
to
be
authenticated
as
they
fetch
sensitive
details
such
as
the
receivedAmount
.
The
specifics
of
this
authentication
are
agreed
by
the
website
and
the
monetization
receiver
when
setting
up
the
receiving
account.
Below
is
a
hypothetical
naive
verification
method
that
will
make
a
request
to
the
incomingPayment
URL
and
simply
return
the
results.
For
simplicity
it
has
no
logic
for
authenticating
the
request.
A
more
sophisticated
implementation
should
track
the
receivedAmount
property
and
ensure
it
is
increasing
after
each
MonetizationEvent
to
verify
that
a
new
payment
has
been
received.
The following example shows how to monetize various types of media using different wallet addresses .
This section is non-normative.
The monetization keyword indicates a wallet address used to monetize the document.
The
monetization
keyword
may
be
used
with
link
elements.
This
keyword
creates
an
external
resource
link
.
The
monetization
keyword
indicates
that
some
aspect
of
the
document
is
monetized.
The
default
type
for
resources
given
by
the
monetization
keyword
is
application/json
.
The appropriate times to fetch and process this type of link are:
When
the
external
resource
link
is
created
on
a
link
element
that
is
already
browsing-context
connected
.
When
the
external
resource
link
's
link
element
becomes
browsing-context
connected
.
When
the
href
attribute
of
the
link
element
of
an
external
resource
link
that
is
already
browsing-context
connected
is
changed.
When
the
disabled
attribute
of
the
link
element
of
an
external
resource
link
that
is
already
browsing-context
connected
is
set,
changed,
or
removed.
When
the
crossorigin
attribute
of
the
link
element
of
an
external
resource
link
that
is
already
browsing-context
connected
is
set,
changed,
or
removed.
When
the
type
attribute
of
the
link
element
of
an
external
resource
link
that
is
already
browsing-context
connected
is
set
or
changed
to
a
value
that
does
not
or
no
longer
matches
the
Content-Type
metadata
of
the
previous
obtained
external
resource,
if
any.
When
the
type
attribute
of
the
link
element
of
an
external
resource
link
that
is
already
browsing-context
connected
,
but
was
previously
not
obtained
due
to
the
type
attribute
specifying
an
unsupported
type,
is
set,
removed,
or
changed.
A user agent MUST NOT delay the load event for this link type.
The
linked
resource
fetch
setup
steps
for
this
type
of
linked
resource,
given
a
link
element
element
and
request
request
,
are:
If element cannot navigate , then return false.
If element 's node document is not allowed to use the "monetization" feature, return false.
Let context be element 's node document 's browsing context .
Set
request
's
initiator
to
"
document
".
Set
request
's
destination
to
"
monetization
".
Set
request
's
mode
to
"
cors
".
Set
request
's
credentials
mode
to
the
CORS
settings
attribute
credentials
mode
for
element
's
crossorigin
content
attribute.
Return true.
To
process
this
type
of
linked
resource
given
a
link
element
element
,
boolean
success
,
and
response
response
:
If response 's status is not an OK status, then set success to false.
Otherwise,
if
response
's
Content-Type
metadata
is
not
application/json
,
then
set
success
to
false.
If the user agent has exhausted the number of allowed payment sessions , set success to false.
"load"
at
element
.
"error"
at
element
.
"monetization"
.
"monetization"
's
extra
permission
data
for
element
's
relevant
settings
object
.
granted
",
establish
a
new
payment
session
If
a
"monetization"
link
is
no
longer
browsing-context
connected
,
a
user
agent
MUST
stop
the
payment
session
.
The
GlobalEventHandlers
interface
is
defined
in
[
HTML
].
WebIDLpartial interface mixin GlobalEventHandlers {
attribute EventHandler onmonetization;
};
onmonetization
The
attribute
must
be
an
event
handler
IDL
attribute
and
event
handler
content
attribute
for
the
event
supported
by
all
element
s,
monetization
Document
objects,
and
Window
objects.
The
user
agent
uses
it
to
notify
that
some
link
has
been
monetized
.
When the payment session has sent a payment with a non-zero amount, perform the following steps:
HTMLLinkElement
associated
with
the
payment
session
.
null
,
then
return.
MonetizationEventInit
dictionary,
whose
members
are
initialized
to
match
payment
's
details.
"monetization"
that
uses
the
MonetizationEvent
interface
at
target
,
with
its
attributes
initialized
with
eventInitDict
,
and
bubbles
initialized
to
true.
The following task source is defined by this specification.
MonetizationEvent
s.
The
MonetizationCurrencyAmount
interface
maps
directly
to
the
PaymentCurrencyAmount
dictionary
as
defined
in
[
payment-request
].
WebIDL[SecureContext, Exposed=Window]
interface MonetizationCurrencyAmount {
readonly attribute DOMString currency;
readonly attribute DOMString value;
};
The
currency
of
the
MonetizationCurrencyAmount.
The
default
is
an
ISO
4217
three-letter
alphabetic
code;
see
the
definition
of
the
currency
member
of
PaymentCurrencyAmount
in
[
payment-request
]
for
details.
The
amount
of
the
MonetizationAmount.
See
the
definition
of
the
value
member
of
PaymentCurrencyAmount
in
[
payment-request
]
for
details.
WebIDL[SecureContext, Exposed=Window]
interface MonetizationEvent : Event {
constructor(DOMString type, MonetizationEventInit eventInitDict);
readonly attribute MonetizationCurrencyAmount amountSent;
readonly attribute USVString? incomingPayment;
readonly attribute USVString walletAddress;
// Following are deprecated
readonly attribute DOMString? amount;
readonly attribute DOMString? assetCode;
readonly attribute octet? assetScale;
readonly attribute DOMString? receipt;
readonly attribute USVString paymentPointer;
};
dictionary MonetizationEventInit : EventInit {
required MonetizationCurrencyAmount amountSent;
required USVString? incomingPayment;
required USVString walletAddress;
// Following are deprecated
required DOMString? amount;
required DOMString? assetCode;
required octet? assetScale;
required DOMString? receipt;
required USVString paymentPointer;
};
The
amount
,
assetCode
,
assetScale
,
paymentPointer
and
receipt
attributes
are
deprecated.
All monetization receivers should be migrating from generating a STREAM Receipt to supporting incoming payments via [ open-payments ] and will no longer be returning receipts to the browser.
As
such
the
MonetizationEvent
no
longer
represents
an
amount
received;
it
represents
an
amount
sent
and
returns
a
URL
as
the
incomingPayment
attribute
that
can
be
used
to
determine
the
amount
received.
The
amount
sent
.
This
should
be
processed
in
the
same
way
as
a
PaymentCurrencyAmount
dictionary
as
defined
in
[
payment-request
].
When
getting,
returns
the
value
it
was
initialized
with.
A URL representing an incoming payment at the monetization receiver . When getting, returns the value it was initialized with.
A URL representing the wallet address that has been monetized. When getting, returns the value it was initialized with.
The amount received as reflected in the receipt from the monetization receiver . When getting, returns the value it was initialized with.
The three letter asset code identifying the amount's units (e.g., "USD" for US dollars). When getting, returns the value it was initialized with.
The
scale
of
the
amount.
For
example,
USD
would
have
an
assetScale
of
2
when
denominated
in
cents.
When
getting,
returns
the
value
it
was
initialized
with.
MonetizationCurrencyAmount
interface
map
directly
to
the
value
and
currency
attributes
of
a
PaymentCurrencyAmount
dictionary.
See
the
documentation
of
PaymentCurrencyAmount
for
guidance
on
processing
and
display
of
these
attributes.
null
or
a
base64-encoded
STREAM
Receipt
issued
by
the
monetization
receiver
to
the
monetization
provider
as
proof
of
the
total
amount
received
in
the
payment
session
.
When
getting,
returns
the
value
it
was
initialized
with.
A URL representing the wallet address that has been monetized. When getting, returns the value it was initialized with.
Web Monetization is a powerful feature that is identified by the name "monetization". Its permission-related algorithms and types are defined as follows:
WebIDLdictionary MonetizationPermissionStorage { float rate = null;
};
PermissionDescriptor
permissionDesc
and
a
PermissionStatus
status
,
the
UA
must:
state
to
permissionDesc
's
permission
state
.The permission state does not depend on a connected wallet. The user agent may skip the prompt if no wallet is connected. When disconnecting a wallet, the "monetization"'s extra permission data type must be cleared.
The user agent may let the user choose a rate for an origin, for example in the permission prompt or in site settings.
Choosing
a
rate
indicates
that
the
user
intends
it
to
be
"monetization"'s
extra
permission
data
for
that
origin.
The
rate
is
never
exposed
to
script:
the
permission
query
algorithm
only
sets
state
.
This
specification
defines
a
policy-controlled
feature
identified
by
the
string
"monetization"
.
Its
default
allowlist
is
'self'
.
This section will eventually be moved into the [ CSP ] and [ FETCH ] specifications.
The monetization-src directive restricts the URLs from which a wallet address is loaded. The syntax for the directive's name and value is described by the following ABNF:
directive-name = "monetization-src"
directive-value
=
serialized-source-list
This directive's pre-request check is as follows:
Given a request ( request ) and a policy ( policy ):
monetization-src
,
and
policy
is
"No",
return
"Allowed".
This directive's post-request check is as follows:
Given a request ( request ) and a policy ( policy ):
monetization-src
,
and
policy
is
"No",
return
"Allowed".
This spec patches the [ CSP ] specification's directive fallback list
Given a string directiveName :
monetization-src
<<
"monetization-src",
"default-src"
>>
<<
>>
.
This spec patches the [ CSP ] specification's effective directive for request
Given a request ( request ):
"monetization"
monetization-src
.
connect-src
.
This spec patches the [ FETCH ] specification's destination type .
A
destination
type
is
one
of:
the
empty
string,
"
audio
",
"
audioworklet
",
"
document
",
"
embed
",
"
font
",
"
frame
",
"
iframe
",
"
image
",
"
json
",
"
manifest
",
"
monetization
",
"
object
",
"
paintworklet
",
"
report
",
"
script
",
"
serviceworker
",
"
sharedworker
",
"
style
",
"
track
",
"
video
",
"
webidentity
",
"
worker
",
or
"
xslt
".
It is RECOMMENDED that a user agent provide some UI or indicator that allows the user to know when monetization is possible and/or when monetization is occurring. Providing such a UI allows the users to retain control of the monetization process by taking action (e.g., stop or start monetization of a particular site if they wish to do so).
As wallet addresses are generally provided as a service, a XSS attack could inject malicious wallet addresses into a page that uses the same service. To mitigate such an attack, it is RECOMMENDED that developers:
monetization-src
CSP
directive
to
restrict
requests
to
origins
they
control
and
trust
to
host
wallet
addresses
.
Web Monetization is designed to be privacy-preserving: The user agent does not send any data to the monetization provider . Instead, it requests data from the monetization provider without ever revealing the URL of the web page the user is currently browsing.
Further, the user agent gets the payment information from the wallet address to establish the payment session . This also ensures the monetization provider doesn't have access to a user's browsing history or to the wallet address .
To
avoid
increasing
the
fingerprinting
surface,
the
"load"
event
is
fired
independently
of
the
permission
state
.
Otherwise
it
could
indicate
whether
the
user
has
connected
a
wallet
or
not.
For
the
same
reason
the
permission
state
remains
"
prompt
"
when
no
wallet
is
connected,
to
not
allow
for
distinction
between
users
who
have
not
granted
permission
yet
and
users
who
have
not
set
up
their
wallet.
This section is non-normative.
Unlike Payment Request API and the Web-based Payment Handler API , which only supports "one-off" payments, Web Monetization provides a payment session that supports both continuous payments and "one-off" payments.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MUST , MUST NOT , and RECOMMENDED in this document are to be interpreted as described in BCP 14 [ RFC2119 ] [ RFC8174 ] when, and only when, they appear in all capitals, as shown here.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: