Web Monetization

Draft Community Group Report

Latest published version:
https://www.w3.org/web-monetization/
Latest editor's draft:
https://webmonetization.org/specification
Editors:
Alex Lakatos (Interledger Foundation)
Adrian Hope-Bailie (Fynbos Technologies Limited)
Former editors:
Nicholas Dudfield (Coil Technologies Inc.) - Until
Ben Sharafian (Coil Technologies Inc.) - Until
Marcos Caceres (W3C) - Until
Feedback:
GitHub wicg/webmonetization (pull requests, new issue, open issues)

Abstract

Web Monetization allows websites to automatically receive payments from users, facilitated by the user agent and a user's preferred monetization provider.

Status of This Document

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.

Warning

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.

1. Usage examples

This section is non-normative.

1.1 Checking if Web Monetization is supported

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.

1.2 Monetizing a web page

1.3 Monetization events

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:

1.4 Verifying a payment

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.

1.5 Monetizing media

The following example shows how to monetize various types of media using different payment pointers.

2. Model

Monetization:
Payments made by a user to a website, facilitated through a monetization provider.
Monetization provider:
The party making payments on behalf of the user. A monetization provider leverages the Interledger Protocol suite of protocols and technologies (e.g., [Open Payments] based on [STREAM]) to provide a high-level way to pay a monetization receiver.
Monetization receiver:
The party receiving payments on behalf of the website, whose details are provided by a payment pointer.
Payment Pointer:
A URL to an Open Payments API entry-point (i.e., a JSON resource containing details that facilitate payment to an account).
Payment session
An session between a monetization provider and monetization receiver initiated by the user agent at the monetization receiver. One or more payments can be initiated by the monetization provider in a single session.

3. Goals

This section is non-normative.

5. onmonetization event handler

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.

6. monetization event

When the payment session has sent a payment with a non-zero amount, perform the following steps:

  1. Let target be the HTMLLinkElement associated with the payment session.
  2. If target is null, then return.
  3. Let eventInitDict be a MonetizationEventInit dictionary, whose members are initialized to match payment's details.
  4. Let event be a newly constructed MonetizationEvent initialized with eventInitDict.
  5. Queue a task on the monetization task source to perform the following steps:
    1. If target is not connected, return.
    2. Fire an event named "monetization" at target, with bubbles initialized to true.

7. Task sources

The following task source is defined by this specifications.

The monetization task source
Used by this specification to queue up non-blocking MonetizationEvents.

8. MonetizationCurrencyAmount interface

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;
};

8.1 currency member

The currency of the MonetizationCurrencyAmount. See the definition of the currency member of PaymentCurrencyAmount in [payment-request] for details.

8.2 value member

The amount of the MonetizationAmount. See the definition of the value member in of PaymentCurrencyAmount in [payment-request] for details.

9. MonetizationEvent interface

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;
};
Warning

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.

9.1 amount attribute (deprecated)

The amount received as reflected in the receipt from the monetization receiver. When getting, returns the value it was initialized with.

9.2 assetCode attribute (deprecated)

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.

9.3 assetScale attribute (deprecated)

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.

Note: MonetizationCurrencyAmount
The members of the 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.

9.4 amountSent attribute

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.

9.5 receipt attribute (deprecated)

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.

9.6 paymentPointer attribute

A URL representing the payment pointer that has been monetized. When getting, returns the value it was initialized with.

9.7 incomingPayment attribute

A URL representing an incoming payment at the monetization receiver. When getting, returns the value it was initialized with.

10. Permissions Policy integration

This specification defines a policy-controlled feature identified by the string "monetization". Its default allowlist is 'self'.

Note
Note

11. Content Security Policy

Note: Monkey patch 🐒

This section will eventually be moved into the [CSP] and [FETCH] specifications.

11.1 monetization-src directive

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-list

11.1.1 monetization-src Pre-request check

This directive's pre-request check is as follows:

Given a request (request) and a policy (policy):

  1. Let name be the result of executing "Get the effective directive for request" on request.
  2. If the result of executing "Should fetch directive execute" on name, monetization-src and policy is "No", return "Allowed".
  3. If the result of executing "Does request match source list?" on request, this directive's value, and policy, is "Does Not Match", return "Blocked".
  4. Return "Allowed".

11.1.2 monetization-src Post-request check

This directive's post-request check is as follows:

Given a request (request) and a policy (policy):

  1. Let name be the result of executing "Get the effective directive for request" on request.
  2. If the result of executing "Should fetch directive execute" on name, monetization-src and policy is "No", return "Allowed".
  3. If the result of executing "Does response to request match source list?" on response, request, this directive's value, and policy, is "Does Not Match", return "Blocked".
  4. Return "Allowed".

12. Security considerations

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:

13. Privacy considerations

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.

14. Relation to Web Payments

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.

A. Conformance

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.

B. References

B.1 Normative references

[CSP]
Content Security Policy Level 3. Mike West; Antonio Sartori. W3C. 4 September 2023. W3C Working Draft. URL: https://www.w3.org/TR/CSP3/
[dom]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[FETCH]
Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[infra]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[Interledger]
Interledger Protocol. URL: https://interledger.org/rfcs/0027-interledger-protocol-4/
[Open Payments]
Open Payments. URL: https://openpayments.guide/
[payment-request]
Payment Request API. Marcos Caceres; Rouslan Solomakhin; Ian Jacobs. W3C. 8 September 2022. W3C Recommendation. URL: https://www.w3.org/TR/payment-request/
[permissions-policy]
Permissions Policy. Ian Clelland. W3C. 12 September 2023. W3C Working Draft. URL: https://www.w3.org/TR/permissions-policy-1/
[Receipt]
STREAM Receipt. URL: https://interledger.org/rfcs/0039-stream-receipts/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[STREAM]
STREAM. URL: https://interledger.org/rfcs/0029-stream/
[url]
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
[webidl]
Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/

B.2 Informative references

[Payment-Handler]
Payment Handler API. Adrian Hope-Bailie; Ian Jacobs; Rouslan Solomakhin; Jinho Bang. W3C. 25 January 2023. W3C Working Draft. URL: https://www.w3.org/TR/payment-handler/