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: