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: