Web Monetization is an API that allows websites to automatically receive micro-payments from users, facilitated by the browser and a user's Web Monetization provider.

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.


Web Monetization provider:
The party making payments on behalf of the user. A Web Monetization provider uses the [[[SPSP]]] (SPSP) on top of the [[[Interledger]]] (ILP)/[[[STREAM]]] to provide a high-level way to send money and data.
Web Monetization receiver:
The party receiving payments on behalf of the website.
Payment end-point:
A [=URL=] to a conforming HTTP SPSP end-point.


Extensions to the `Document` interface

        partial interface Document {
          readonly attribute Monetization monetization;


This flow refers to the user agent and the user's provider.

  1. The user agent sets {{ Monetization / state }} to "{{ MonetizationState / pending }}".
  2. The user agent observes the [^head^] and looks for a Web Monetization <meta name="monetization"> tag (specified below).

    • There MUST be only one <meta name="monetization"> tag at any given time
    • The `<meta>` Tags Set MUST be in the [^head^] of the document.
    • The `<meta>` Tags Set MUST be in the top level window (i.e. not inside an iframe)
  3. Below is repeated for every semantically (consider meta.content = meta.content) new <meta name="monetization"> tag seen for the life of the page:

    • If any of the Web Monetization `<meta>` Tags Set are malformed, the browser will stop here. The user agent SHOULD report a warning via the console.
    • If the Web Monetization <meta name="monetization"> tag is well-formed, the browser should extract the Payment Setup Endpoint (Payment Pointer or SPSP Url).
    • The user agent generates a fresh random UUID (version 4) and uses this as a Monetization ID. This MUST be regenerated upon dynamic changes to the meta tags and MUST be unique per page load in order to avoid user tracking.
    • The user agent passes these payment details to the user's provider (see Payment Handler Flow).
    • The provider resolves the Payment Setup Endpoint and begins to pay. The provider MAY be acting from a different machine from the user. Cookies and session information MUST NOT be carried with any requests made to resolve the Payment Setup Endpoint, with the exception of the Monetization ID.
      • With the destination_account and shared_secret fetched from the SPSP query, a [[[STREAM]]] connection is established. A single [[[STREAM]]] is opened on this connection, and a positive SendMax is set.
      • The provider SHOULD set their SendMax high enough that it is never reached, and make payment adjustments by limiting throughput.
    • Once the [[[STREAM]]] connection has fulfilled an ILP packet with a non-zero amount, the provider notifies the browser:
      • The user agent sets document.monetization.state to started.
      • This MUST occur before the `start` event is fired.
      • This event is a {{ MonetizationStartEvent }} containing the Payment Setup Endpoint and the Monetization ID as properties.
      • The user agent also emits a {{ progress }} event from document.monetization, corresponding to this first packet.
    • Payment continues for the lifetime of a given meta tag (or semantically equivalent)
      • The provider MAY decide to stop/start payment at any time, e.g. if the user is idle, backgrounds the page, or instructs the browser to do so.
      • If the [[[STREAM]]] connection is severed, the provider will redo the SPSP query to the same Payment Setup Endpoint as before with the same Monetization ID. The user agent MUST NOT re-process the `<meta>` Tags Set.
      • Each time a packet with a non-zero amount is fulfilled, the provider notifies the browser, and the browser emits a {{ MonetizationProgressEvent }} on document.monetization. The event has details of the packet.
      • When a stream is closed the document.monetization.state MUST be set back to 'pending'

Payment Handler Flow

A provider can be implemented as a Payment Handler supporting the 'webmonetization' payment method (The payment method specification for this payment method is still under development as it is dependant on changes to the Payment Handler API that support streaming payments). Communication between the browser and the provider would use this flow.

          "supportedMethods": "webmonetization",
          "data": {
            "paymentPointer": "<payment pointer parsed from meta tag>"


Meta Tags Set

The `<meta>` Tags Set MUST be in the document's [^head^]. The `<meta>` Tags Set allows the user agent to pay a site via Web Monetization by specifying a Payment Pointer or SPSP url.

The name of the `<meta>` tags all start with monetization. The table below lists the different names and the formats of their content. Currently there is only one tag, but this may be expanded in the future so care MUST be given to altering a Tags Set such that <meta name="monetization"> is the last one modified.

Name Required? Format Description
monetization Yes Payment Setup Endpoint The Payment Pointer or SPSP url that the user agent will pay to.


Web Monetization Meta Tag
    <meta name="monetization" content="$wallet.example.com/alice">

Monetization interface

          [Exposed=Window, SecureContext]
          interface Monetization : EventTarget {
            readonly attribute MonetizationState state;
            attribute EventHandler onstart;
            attribute EventHandler onprogress;
state attribute
A {{ Monetization / state }} attribute exposes the current state of Web Monetization as a {{ MonetizationState }} enum value.
onstart attribute
A {{ Monetization / onstart }} attribute is an {{ EventHandler }} for a {{ MonetizationStartEvent }} named "start".
onprogress attribute
A {{ Monetization / onprogress }} attribute is an {{ EventHandler }} for an {{ MonetizationProgressEvent }} named "progress".

MonetizationState enum

            enum MonetizationState {
Indicates that monetization has not yet started. This is set even if there are no Web Monetization [^meta^] elements in the document.
Indicates that monetization has started (i.e. the user agent fired the `"start"` event).



Event name Interface Dispatched when… Target
start {{ MonetizationStartEvent }} The first non-zero payment is successfully sent. {{ Document / monetization }} attribute
progress {{ MonetizationProgressEvent }} A payment is successfully made to the receiver. {{ Document / monetization }}

MonetizationStartEvent interface

            [SecureContext, Exposed=Window]
            interface MonetizationStartEvent : Event {
              constructor(DOMString type, MonetizationStartEventInit eventInitDict);
              readonly attribute DOMString paymentPointer;
              readonly attribute DOMString requestId;


The constructor() for {{ MonetizationStartEvent }} behaves as follows:

  1. ...TBW...

paymentPointer attribute

When getting, returns the value it was initialized with. See {{ MonetizationStartEventInit / paymentPointer }} member of {{ MonetizationStartEventInit }} for more information.

requestId attribute

When getting, returns the value it was initialized with. See {{ MonetizationStartEventInit / requestId }} member of {{ MonetizationStartEventInit }} for more information.

MonetizationStartEventInit dictionary

Dispatched once the first ILP packet with a non-zero amount has been fulfilled by the page's SPSP receiver. MUST be dispatched at least once if payment occurs.

                dictionary MonetizationStartEventInit : EventInit {
                  required DOMString paymentPointer;
                  required DOMString requestId;
paymentPointer member
A string representing the Payment Pointer resolved from the <meta name="monetization"> tag.
requestId member
The Monetization ID (UUID V4) generated by the browser (see [[[#flow]]]).

MonetizationProgressEvent interface

Dispatched every time an ILP packet with a non-zero amount has been fulfilled by the page's Web Monetization receiver (including the first time, when `start` event is also dispatched).

            [SecureContext, Exposed=Window]
            interface MonetizationProgressEvent : Event {
              constructor(DOMString type, MonetizationProgressEventInit eventInitDict);
              readonly attribute DOMString amount;
              readonly attribute DOMString assetCode;
              readonly attribute DOMString assetScale;
              readonly attribute DOMString? receipt;


The constructor() for {{ MonetizationProgressEvent }} behaves as follows:

  1. ...TBW...

amount attribute

When getting, returns the value it was initialized with. See {{ MonetizationProgressEventInit / amount }} member of {{ MonetizationProgressEventInit }} for more information.

assetCode attribute

When getting, returns the value it was initialized with. See {{ MonetizationProgressEventInit / assetCode }} member of {{ MonetizationProgressEventInit }} for more information.

assetScale attribute

When getting, returns the value it was initialized with. See {{ MonetizationProgressEventInit / assetScale }} member of {{ MonetizationProgressEventInit }} for more information.

receipt attribute

When getting, returns the value it was initialized with. See {{ MonetizationProgressEventInit / receipt }} member of {{ MonetizationProgressEventInit }} for more information.

MonetizationProgressEventInit dictionary

              dictionary MonetizationProgressEventInit : EventInit {
                required DOMString amount;
                required DOMString assetCode;
                required DOMString assetScale;
                DOMString receipt;
amount member
The destination amount received as specified in the ILP packet.
assetCode member
The three letter asset code describing the amount's units.
assetScale member
The scale of the amount. For example, USD would have an assetScale of 2 when denominated in cents.
receipt member
base64-encoded [[[Receipt]]] issued by the Web Monetization receiver to the Web Monetization provider as proof of the total amount received in the stream.

HTTP Headers


DEPRECATED: The `Web-Monetization-Id` header is deprecated in favor of receipts.

Contains the `Monetization ID` (currently referred to as {{ MonetizationStartEvent / requestId }} in the {{ MonetizationStartEvent }}) as a a UUID version 4, which the user agent generated. This header MAY be sent on [[SPSP]] queries for Web Monetization.

          Web-Monetization-Id: dcd479ad-7d8d-4210-956a-13c14b8c67eb

Relation to other technologies

Unlike [[[payment-Request]]] and the [[[Payment-Handler]]], Web Monetization is intended for continuous payments rather than discrete payments. Additionally, it is designed to not require any user interaction, serving as an alternative to traditional e-commerce checkout methods.