Web Monetization

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 is a preview

Do not attempt to implement this version of the specification. Do not reference this version as authoritative in any way. Instead, see https://webmonetization.org/specification for the Editor's draft.

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

Note

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.

Example 1

<link rel="monetization" href="https://example.com/pay">
<script>
  const link = document.createElement("link");

  if (link.relList.supports("monetization")) {
    console.log("Web Monetization is supported.");
  }
</script>

Example 2

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>My Blog</title>
    <link
      rel="monetization"
      href="https://example.com/pay"
      onmonetization="sayThanks(this)"
   >
    <script>
      function sayThanks(monetizedLink) {
        // Do something here
      }
    </script>
  </head>
  <body></body>
</html>

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:

Example 3

<link rel="monetization" href="https://example.com/pay">
<script>
  const link = document.querySelector('link[rel="monetization"]')
  link.addEventListener('monetization', (event) => {
    // See how much was sent and in what currency
    const {
      amountSent: { value, currency },
    } = event
    console.log(`Browser sent ${currency} ${value}.`)

    // Use the incoming payment URL to verify the payment at the receiver.
    verifyPayment(event)
  })
</script>

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.

Example 4

/** @type {MonetizationEvent} event */
// eslint-disable-next-line @typescript-eslint/no-unused-vars
async function verifyPayment(event) {
  // Legacy receivers don't support returning incoming payment URLs
  if (!event.incomingPayment) {
    throw new Error('No incoming payment URL')
  }

  // Poll the incoming payment to check the amount received
  const response = await fetch(event.incomingPayment, {
    credentials: 'same-origin',
    mode: 'same-origin',
    cache: 'no-cache',
    headers: {
      'Content-Type': 'application/json',
    },
  })

  if (response.ok) {
    // The incoming payment was fetched successfully
    const { receivedAmount } = await response.json()
    const { amount, assetCode, assetScale } = receivedAmount
    // eslint-disable-next-line no-console
    console.log(`Received ${assetCode}${amount / 10 ** assetScale}.`)
    return receivedAmount
  }
}

The following example shows how to monetize various types of media using different wallet addresses.

Example 5

<video src="myvideo" onmonetization="sayThanks(this)">
  <link rel="monetization" href="https://example.com/video/pay">
</video>

<audio src="music.mp3" onmonetization="sayThanks(this)">
  <link rel="monetization" href="https://example.com/audio/pay">
</audio>

<picture srcset="cat.jpeg" onmonetization="sayThanks(this)">
  <link rel="monetization" href="https://example.com/images/pay">
</picture>

Issue 1

Note: Multiple monetization links

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.
Let json be the result of parse JSON bytes to an Infra value passing response's body.
If json is an exception, then set success to false.
If the user agent has exhausted the number of allowed payment sessions, set success to false.
Queue an element task on the networking task source given element and the following steps:
1. If success is true, fire an event named "load" at element.
2. Otherwise, fire an event named "error" at element.
Let state be the result of get the current permission state with "monetization".
Let rate be "monetization"'s extra permission data for element's relevant settings object.
If success is true and state is "granted", establish a new payment session using rate.

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 monetization event supported by all elements, 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:

Let target be the HTMLLinkElement associated with the payment session.
If target is null, then return.
Let eventInitDict be a MonetizationEventInit dictionary, whose members are initialized to match payment's details.
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" that uses the MonetizationEvent interface at target, with its attributes initialized with eventInitDict, and bubbles initialized to true.

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

Warning

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.

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.

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:

extra permission data type

A rate, which is either null or a positive number representing the maximum amount to pay per hour in the wallet address's asset currency and asset scale. Null means the user agent uses its default rate.

WebIDLdictionary MonetizationPermissionStorage {
  float rate = null;
};

extra permission data constraints

If not null, the rate MUST be greater than zero.

permission query algorithm

To query the "monetization" permission with a PermissionDescriptor permissionDesc and a PermissionStatus status, the UA must:

Set status's state to permissionDesc's permission state.

permission revocation algorithm

To revoke the "monetization" permission, the UA must:

Stop all payment sessions established by a Document matching the relevant origin.
Set the "monetization"'s extra permission data type to null.

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.

Note

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'.

Note

Example 6

Given a page embedding the following iframe, monetization is allowed for the embedded document:

<iframe src="https://example.com/" allow="monetization"></iframe>

Example 7

Given a page with the following Permission Policy:

Permissions-Policy: monetization=(self "https://example.com")

Monetization is allowed for the page itself and for any embedded content from https://example.com.

Note: Monkey patch 🐒

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

Example 8

Given a page with the following Content Security Policy:

Content-Security-Policy: monetization-src https://example.com/

Fetches for the following code will return a network error, as the URL provided does not match monetization-src's source list:

<link rel="monetization" href="https://example.org/wallet-address">

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

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

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

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

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

Let name be the result of executing "Get the effective directive for request" on request.
If the result of executing "Should fetch directive execute" on name, monetization-src, and policy is "No", return "Allowed".
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".
Return "Allowed".

This spec patches the [CSP] specification's directive fallback list

Given a string directiveName:

Switch on directiveName:
...

monetization-src

<< "monetization-src", "default-src" >>
Return << >>.

This spec patches the [CSP] specification's effective directive for request

Given a request (request):

...
Switch on request's destination:
...
"monetization"
1. Return monetization-src.
Return 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".

[CSP]: Content Security Policy Level 3. Mike West; Antonio Sartori. W3C. 13 August 2026. 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; Dominic Farolino; 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/developers/rfcs/interledger-protocol/
[open-payments]: Open Payments. URL: https://openpayments.dev/
[payment-request]: Payment Request API. Marcos Caceres; Ian Jacobs; Stephen McGruer. W3C. 22 June 2026. CRD. URL: https://www.w3.org/TR/payment-request/
[permissions]: Permissions. Marcos Caceres; Mike Taylor. W3C. 6 October 2025. W3C Working Draft. URL: https://www.w3.org/TR/permissions/
[permissions-policy]: Permissions Policy. Ian Clelland. W3C. 18 June 2026. W3C Working Draft. URL: https://www.w3.org/TR/permissions-policy-1/
[Receipt]: STREAM Receipt. URL: https://interledger.org/developers/rfcs/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/info/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/info/rfc8174/
[STREAM]: STREAM. URL: https://interledger.org/developers/rfcs/stream-protocol/
[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/

[Payment-Handler]: Web-based Payment Handler API. Ian Jacobs; Jinho Bang; Stephen McGruer. W3C. 23 April 2026. W3C Working Draft. URL: https://www.w3.org/TR/web-based-payment-handler/

Web Monetization

Abstract

Status of This Document

1. Usage examples

1.1 Checking if Web Monetization is supported

1.2 Monetizing a web page

1.3 Monetization events

1.4 Verifying a payment

1.5 Monetizing media

2. Model

3. Goals

4. Link type "monetization"

5. Events

5.1 Extensions to GlobalEventHandlers interface

5.2 monetization event

6. Task sources

7. MonetizationCurrencyAmount interface

7.1 currency member

7.2 value member

8. MonetizationEvent interface

8.1 amountSent attribute

8.2 incomingPayment attribute

8.3 walletAddress attribute

8.4 amount attribute (deprecated)

8.5 assetCode attribute (deprecated)

8.6 assetScale attribute (deprecated)

8.7 receipt attribute (deprecated)

8.8 paymentPointer attribute (deprecated)

9. Permissions integration

10. Permissions Policy integration

11. Content Security Policy

11.1 monetization-src directive

11.1.1 monetization-src Pre-request check

11.1.2 monetization-src Post-request check

11.1.3 Get fetch directive fallback list

11.1.4 Get the effective directive for request

11.1.5 Fetch destination type

12. Security considerations

13. Privacy considerations

14. Relation to Web Payments

A. Conformance

B. References

B.1 Normative references

B.2 Informative references

5.1 Extensions to `GlobalEventHandlers` interface

5.2 `monetization` event

7. `MonetizationCurrencyAmount` interface

7.1 `currency` member

7.2 `value` member

8. `MonetizationEvent` interface

8.1 `amountSent` attribute

8.2 `incomingPayment` attribute

8.3 `walletAddress` attribute

8.4 `amount` attribute (deprecated)

8.5 `assetCode` attribute (deprecated)

8.6 `assetScale` attribute (deprecated)

8.7 `receipt` attribute (deprecated)

8.8 `paymentPointer` attribute (deprecated)

11.1.1 `monetization-src` Pre-request check

11.1.2 `monetization-src` Post-request check