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.
This specification is a work in progress and will be updated as discussions progress within the WIGC. Please see the explainer for more info.
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.
partial interface Document { readonly attribute Monetization monetization; };
This flow refers to the user agent and the user's provider.
The user agent observes the [^head^] and
looks for a Web Monetization
<meta name="monetization">
tag (specified below).
<meta name="monetization">
tag at any
given time
Below is repeated for every semantically (consider
meta.content = meta.content
) new
<meta name="monetization">
tag seen for
the life of the page:
<meta name="monetization">
tag is
well-formed, the browser should extract the Payment Setup Endpoint
(Payment Pointer or
SPSP
Url).
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.
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.
document.monetization.state
to
started
.
document.monetization
, corresponding to this
first packet.
document.monetization
. The event has details of
the packet.
document.monetization.state
MUST be set back to
'pending'
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>" } }
.show()
on this
PaymentRequest, triggering the
PaymentHandler
for webmonetization
. This PaymentHandler is how the
browser communicates to the provider.
.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.
[Exposed=Window, SecureContext] interface Monetization : EventTarget { readonly attribute MonetizationState state; attribute EventHandler onstart; attribute EventHandler onprogress; };
enum MonetizationState { "pending", "started" };
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}} |
[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:
When getting, returns the value it was initialized with. See {{MonetizationStartEventInit/paymentPointer}} member of {{MonetizationStartEventInit}} for more information.
When getting, returns the value it was initialized with. See {{MonetizationStartEventInit/requestId}} member of {{MonetizationStartEventInit}} for more information.
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; };
<meta name="monetization">
tag.
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; };
The constructor() for {{MonetizationProgressEvent}} behaves as follows:
When getting, returns the value it was initialized with. See {{MonetizationProgressEventInit/amount}} member of {{MonetizationProgressEventInit}} for more information.
When getting, returns the value it was initialized with. See {{MonetizationProgressEventInit/assetCode}} member of {{MonetizationProgressEventInit}} for more information.
When getting, returns the value it was initialized with. See {{MonetizationProgressEventInit/assetScale}} member of {{MonetizationProgressEventInit}} for more information.
dictionary MonetizationProgressEventInit : EventInit { required DOMString amount; required DOMString assetCode; required DOMString assetScale; };
assetScale
of 2
when denominated in
cents.
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