Web Monetization is an API that allows websites to request small payments from users facilitated by the browser and the user's Web Monetization provider.

Terminology

User:

the party who is accessing the web-monetized website.

Website:

the web-monetized website.

Web Monetization provider:

the party making payments on behalf of the user.

Web Monetization receiver:

the party receiving payments on behalf of the website.

User agent:

the web browser used by the user.

Extensions to the `Document` interface

        partial interface Document {
          readonly attribute Monetization monetization;
        };
      

Flow

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.
     • On the SPSP query to resolve the Payment Setup Endpoint, a Web-Monetization-Id header is sent, containing the Monetization ID. The server running the web-monetized site may use this to associate future requests by the user with their payments.
     • 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.

• After parsing the `<meta>` Tags Set, the browser creates a new PaymentRequest object with the following PaymentMethodData argument.

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

• The user agent calls .show() on this PaymentRequest, triggering the PaymentHandler for webmonetization. This PaymentHandler is how the browser communicates to the provider.
  • The return value of .show() MUST return a Promise, and must also implement the {{EventTarget}} interface. The provider will emit {{MonetizationStartEvent}} and {{MonetizationProgressEvent}} events from this Promise to communicate to the browser when payment occurs. The Promise MUST NOT resolve, because Web Monetization continues for the entire lifetime of a given meta tag. The Promise MAY reject if there is an error preventing the provider from paying and no retries will occur.
  • This PaymentHandler MUST NOT require any UI or confirmation to proceed with payment.

Specification

    <meta name="monetization" content="$twitter.xrptipbot.com/interledger">
          

          [Exposed=Window, SecureContext]
          interface Monetization : EventTarget {
            readonly attribute MonetizationState state;
            attribute EventHandler onstart;
            attribute EventHandler onprogress;
          };
        

            enum MonetizationState {
              "pending",
              "started"
            };
          

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

                dictionary MonetizationStartEventInit : EventInit {
                  required DOMString paymentPointer;
                  required DOMString requestId;
                };
              

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

              dictionary MonetizationProgressEventInit : EventInit {
                required DOMString amount;
                required DOMString assetCode;
                required DOMString assetScale;
              };
            

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