Copyright © 2023 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 explainer 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.
There are multiple ways to check if Web Monetization is supported. One
way is to call
supports() on a
link
element's
relList
passing the "monetization"
keyword. Alternatively, you can check if either the
MonetizationEvent
interface or the "onmonetization"
event handler IDL attribute
exist on the
Window
object.
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 payment pointers.
This section is non-normative.
The monetization keyword indicates a payment pointer 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 is:
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, the set success to false.
Otherwise, if response's
Content-Type metadata is not a
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.
If a "monetization" link
becomes browsing-context disconnected, a user agent
MUST stop the
payment session.
The onmonetization event handler is an
event handler content attribute
that can be applied to any
element. 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.
MonetizationEvent
initialized with
eventInitDict.
"monetization" at
target, with
bubbles
initialized to true.
The following task source is defined by this specifications.
MonetizationEvents.
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. 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 in of
PaymentCurrencyAmount
in [payment-request] for details.
WebIDL[SecureContext, Exposed=Window]
interface MonetizationEvent : Event {
constructor(DOMString type, MonetizationEventInit eventInitDict);
readonly attribute DOMString? amount;
readonly attribute DOMString? assetCode;
readonly attribute octet? assetScale;
readonly attribute DOMString? receipt;
readonly attribute MonetizationCurrencyAmount amountSent;
readonly attribute USVString paymentPointer;
readonly attribute USVString? incomingPayment;
};
dictionary MonetizationEventInit : EventInit {
required DOMString? amount;
required DOMString? assetCode;
required octet? assetScale;
required DOMString? receipt;
required PaymentCurrencyAmount amountSent;
required USVString paymentPointer;
required USVString? incomingPayment;
};
The amount, assetCode,
assetScale 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 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.
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.
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 payment pointer that has been monetized. 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.
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 payment pointer 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-listThis 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".
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 payment pointers are generally provided as a service (e.g., Uphold), a XSS attack could inject malicious payment pointers 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
payment pointers.
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 payment pointer to establish the payment session. This also ensures the monetization provider doesn't have access to a user's browsing history or to the payment pointer.
This section is non-normative.
Unlike Payment Request API and the 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: