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.
Browser:
is 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 API and the Payment Handler API.

The reason this API is not using the Payment Request API directly is that Web Monetization is intended for continuous payments rather than discrete payments. It is also not designed to have any user interaction. It is intended to provide a direct alternative to advertisements, rather than an alternative to existing checkout methods.

Some changes will be required to Payment Request and Payment Handler to fully support Web Monetization in future, however this API brings the necessary features to the browser in a way that allows for tighter integration in the future.

With advertisements, the user's browser 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.

Flow

This flow refers to the user's browser and the user's provider, defined above.

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's browser 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's browser will pay to.

Examples

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

Monetization interface

              [Exposed=Window]
              interface Monetization : EventTarget {
                readonly attribute DOMString state;
    
                attribute EventHandler onmonetizationstart;
                attribute EventHandler onmonetizationprogress;
              };
          
state attribute
A {{ Monetization }}'s state attribute exposes the current state of Web Monetization.
onmonetizationstart attribute
A {{ Monetization }}'s onmonetizationstart attribute is an {{EventHandler}} for a {{ MonetizationStartEvent }} named "monetizationstart".
onmonetizationprogress attribute
A {{ Monetization }}'s onmonetizationprogress attribute is an {{EventHandler}} for an {{ MonetizationStartEvent }} named "monetizationprogress".

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< tags on the page.
"started"
Indicates that monetization has started (i.e. the monetizationstart event has been fired).

Events

Summary

Event name Interface Dispatched when… Target
monetizationstart {{MonetizationStartEvent}} The first non-zero payment is successfully sent. {{Monetization}}
monetizationprogress {{MonetizationProgressEvent}} A payment is successfully made to the receiver. {{Monetization}}

MonetizationStartEvent interface

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

paymentPointer attribute

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

requestId attribute

When getting, returns the value it was initialized with. See 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 {
                  DOMString paymentPointer;
                  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 monetizationstart is also dispatched). This event MAY NOT be emitted if there are no listeners for it on document.monetization.

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

amount attribute

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

assetCode attribute

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

assetScale attribute

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

MonetizationProgressEventInit dictionary

                dictionary MonetizationProgressEventInit : EventInit {
                  DOMString amount;
                  DOMString assetCode;
                  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 the scale of the amount. For example, cents would have an assetScale of 2.

HTTP Headers

Web-Monetization-Id

Contains the Monetization ID (currently referred to as requestId in the events) that the browser generated. This header MUST always be sent on SPSP queries for Web Monetization. This value MUST be a UUID version 4.

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