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.

Introduction

This specification is a work in progress and will be updated as discussions progress within the WIGC. Please see the explainer for more info.

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.

Goals

Relation to other protocols

The W3C have published two payments related APIs for browsers, the [[[payment-Request]]] and the [[[Payment-Handler]]].

The reason this API is not using the [[[payment-Request]]] directly is that Web Monetization is intended for continuous payments rather than discrete payments. It is also designed to not have any user interaction: It is intended to provide a direct alternative to advertisements, rather than an alternative to traditional e-commerce checkout methods.

In future, some changes will be required to the [[[payment-Request]]] and the [[[Payment-Handler]]] to support Web Monetization. This API brings the necessary capabilities to user agents in a manner that can integrate with existing payments APIs.

With advertisements, the user agent decides whether to display the ads and the user decides whether to engage with the ads. With Web Monetization, the user's provider decides whether to pay the site and, if so, how much to pay.

Web Monetization makes use of SPSP on top of ILP/STREAM to provide a high-level way to send money and data, while still providing tremendous flexibility.

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.

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

Specification

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.

Examples

Web Monetization Meta Tag
    <meta name="monetization" content="$twitter.xrptipbot.com/interledger">
          

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 {{MonetizationStartEvent}} named "progress".

MonetizationState enum

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

Events

Summary

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

`constructor()`

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

`constructor()`

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.

MonetizationProgressEventInit dictionary

              dictionary MonetizationProgressEventInit : EventInit {
                required DOMString amount;
                required DOMString assetCode;
                required DOMString assetScale;
              };
            
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.

HTTP Headers

`Web-Monetization-Id`

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 MUST always be sent on [[SPSP]] queries for Web Monetization.

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