Skip to content

feat(spec/ext) specify getWallet/onPayment #664

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
asurkov merged 2 commits into from
May 13, 2026
Merged

feat(spec/ext) specify getWallet/onPayment #664

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c9b4b52
feat(spec/ext) specify getWallet/onPayment
asurkov May 1, 2026
686a266
address comments
asurkov May 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 51 additions & 25 deletions specification/extensions-api/section/events.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,10 @@
<h2>Events</h2>

<p>
Events in this namespace are scoped to a {{ Document }},
identified by its tab and frame. Each event callback receives a
{{MonetizationInfo}} dictionary describing the affected document.
Events in this namespace are scoped to a [[WebMonetization]]
session. Each event callback receives a
{{monetization/Session}} dictionary identifying the affected
session and the document it belongs to.
</p>

<section data-dfn-for="monetization">
Expand All @@ -15,21 +16,19 @@ <h3><dfn>onStarted</dfn></h3>
)</pre>

<p>
Fired when the first [[WebMonetization]] session becomes active
in a document. Subsequent sessions starting in the same document
do <em>not</em> re-fire this event.
Fired when a [[WebMonetization]] session starts in a document.
</p>

<h4>Parameters</h4>
<dl>
<dt><code>callback</code></dt>
<dd>
<p>The <code>callback</code> parameter looks like:</p>
<pre>(info: {{MonetizationInfo}}) =&gt; void</pre>
<pre>(session: {{monetization/Session}}) =&gt; void</pre>
<dl>
<dt><code>info</code></dt>
<dd>The {{MonetizationInfo}} for the document where
monetization started.</dd>
<dt><code>session</code></dt>
<dd>The {{monetization/Session}} for the session that
started.</dd>
</dl>
</dd>
</dl>
Expand All @@ -38,26 +37,26 @@ <h4>Parameters</h4>
<section data-dfn-for="monetization">
<h3><dfn>onStopped</dfn></h3>

<pre>browser.monetization.onStopped.addListener(
<pre class="example">browser.monetization.onStopped.addListener(
callback: function,
)</pre>

<p>
Fired when the last [[WebMonetization]] session in a document
has ended. This occurs when the tab is closed, the document
navigates away, or all sessions are explicitly stopped.
Fired when a [[WebMonetization]] session ends. This occurs when
the tab is closed, the document navigates away, or the session
is explicitly stopped.
</p>

<h4>Parameters</h4>
<dl>
<dt><code>callback</code></dt>
<dd>
<p>The <code>callback</code> parameter looks like:</p>
<pre>(info: {{MonetizationInfo}}) =&gt; void</pre>
<pre>(session: {{monetization/Session}}) =&gt; void</pre>
<dl>
<dt><code>info</code></dt>
<dd>The {{MonetizationInfo}} for the document where
monetization stopped.</dd>
<dt><code>session</code></dt>
<dd>The {{monetization/Session}} for the session that
stopped.</dd>
</dl>
</dd>
</dl>
Expand All @@ -67,13 +66,40 @@ <h4>Parameters</h4>
<h3>Event ordering</h3>

<p>
For a given document, an {{monetization/onStarted}} event is always
delivered before any corresponding {{monetization/onStopped}} event.
If a document has multiple concurrent sessions, intermediate
session starts and stops do not produce additional events.
Only the transition from zero to one active session
({{monetization/onStarted}}) and from one to zero active sessions
({{monetization/onStopped}}) fire events.
For a given session, an {{monetization/onStarted}} event is
always delivered before the corresponding
{{monetization/onStopped}} event. A document with multiple
concurrent sessions receives a separate
{{monetization/onStarted}} and {{monetization/onStopped}} pair
for each session.
</p>
</section>

<section data-dfn-for="monetization">
<h3><dfn>onPayment</dfn></h3>

<pre class="example">browser.monetization.onPayment.addListener(
callback: function,
)</pre>

<p>
Fired when a payment is sent for a monetization session. The
updated budget balance can be retrieved via
{{monetization/getWallet()}}.
</p>

<h4>Parameters</h4>
<dl>
<dt><code>callback</code></dt>
Comment thread
asurkov marked this conversation as resolved.
<dd>
<p>The <code>callback</code> parameter looks like:</p>
<pre>(session: {{monetization/Session}}) =&gt; void</pre>
<dl>
<dt><code>session</code></dt>
<dd>The {{monetization/Session}} for the session that
triggered the payment.</dd>
</dl>
</dd>
</dl>
</section>
</section>
30 changes: 27 additions & 3 deletions specification/extensions-api/section/interfaces.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,40 @@ <h2>The <code>monetization</code> namespace</h2>

<p>
The <dfn>monetization</dfn> namespace is the entry point for the
Web Monetization Extensions API. It exposes events that allow
extensions to observe monetization session state changes within
documents.
Web Monetization Extensions API. It exposes methods for querying
wallet state and budget balance, and events that allow extensions
to observe monetization session lifecycle and payment activity.
</p>

<p class="note">
The full <code>chrome.monetization</code> API includes additional
methods for wallet connection management and session history that
are available only to the browser's built-in WebUI. This
specification covers the subset exposed to privileged browser
extensions.
</p>

<pre class="idl">
[Exposed=Window]
namespace monetization {
Promise&lt;Wallet?&gt; getWallet();

readonly attribute EventHandler onStarted;
readonly attribute EventHandler onStopped;
readonly attribute EventHandler onPayment;
};
</pre>

<section data-dfn-for="monetization">
<h3>Methods</h3>

<section>
<h4><dfn>getWallet()</dfn></h4>
<p>
Returns the connected user wallet, including its current
budget balance. Resolves with <code>null</code> if no wallet
is connected.
</p>
</section>
</section>
</section>
118 changes: 110 additions & 8 deletions specification/extensions-api/section/types.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,115 @@
<section id="types">
<h2>Types</h2>

<section data-dfn-for="MonetizationInfo">
<h3><dfn>MonetizationInfo</dfn></h3>
<p class="note">
Type names defined here are scoped under the
<a>monetization</a> namespace. Implementations expose them as
namespace-scoped dictionaries on `chrome.monetization`
(for example, {{monetization/Wallet}} corresponds to
`chrome.monetization.Wallet`).
</p>

<section data-dfn-for="monetization/Wallet">
<h3><dfn data-dfn-for="monetization">Wallet</dfn></h3>

<p>
Describes the document where a monetization state change occurred.
Describes the connected user wallet, including its current
budget balance.
</p>

<pre class="idl">
dictionary MonetizationInfo {
enum ReconnectReason {
"unauthorized"
};

dictionary Wallet {
required DOMString address;
Comment thread
asurkov marked this conversation as resolved.
required DOMString name;
Comment thread
asurkov marked this conversation as resolved.
required DOMString currency;
required DOMString initialBalance;
required DOMString remainingBalance;
DOMString? renewDate;
ReconnectReason? reconnectReason;
};
</pre>

<h4>Properties</h4>
<dl>
<dt><dfn>address</dfn></dt>
<dd>
The canonical wallet address URL, as returned in the `id`
field of the Open Payments wallet address resource. This is
the resolved address (e.g.
`"https://ilp.example.com/123456/usd"`), which may differ
from the URL the user originally entered (such as a
`.well-known/pay` shortcut).
</dd>

<dt><dfn>name</dfn></dt>
<dd>
A human-readable name for the wallet.
</dd>

<dt><dfn>currency</dfn></dt>
<dd>
An ISO 4217 currency code (e.g. `"USD"`).
</dd>

<dt><dfn>initialBalance</dfn></dt>
<dd>
A decimal string representing the total budget allocated for
the current billing period (e.g. `"10.00"`).
</dd>

<dt><dfn>remainingBalance</dfn></dt>
<dd>
A decimal string representing the budget remaining for the
current billing period (e.g. `"7.50"`).
</dd>

<dt><dfn>renewDate</dfn></dt>
<dd>
An ISO 8601 date string indicating when the budget next renews.
Absent when the budget does not renew monthly.
</dd>

<dt><dfn>reconnectReason</dfn></dt>
<dd>
When present, indicates that the wallet must be reconnected
before it can be used, and conveys the reason. When absent,
the wallet is usable. Possible values:
<dl>
<dt>`"unauthorized"`</dt>
<dd>
The stored access token is no longer valid (for example,
it has expired or been revoked).
</dd>
</dl>
</dd>
</dl>

<p class="note">
The {{Wallet/currency}}, {{Wallet/initialBalance}}, and
{{Wallet/remainingBalance}} members use the same conventions as the
`currency` and `value` members of the {{PaymentCurrencyAmount}}
dictionary defined in [[payment-request]] (and the
`MonetizationCurrencyAmount` interface in [[WebMonetization]]).
</p>
</section>

<section data-dfn-for="monetization/Session">
<h3><dfn data-dfn-for="monetization">Session</dfn></h3>

<p>
Identifies a monetization session and the document it belongs to.
</p>

<pre class="idl">
dictionary Session {
required long tabId;
required long frameId;
required DOMString url;
required long sessionId;
required DOMString walletAddress;
};
</pre>

Expand All @@ -26,12 +123,17 @@ <h4>Properties</h4>
<dt><dfn>frameId</dfn></dt>
<dd>
The identifier of the frame within the tab.
<code>0</code> denotes the top-level (main) frame.
`0` denotes the top-level (main) frame.
</dd>

<dt><dfn>sessionId</dfn></dt>
<dd>
The identifier of the monetization session.
</dd>

<dt><dfn>url</dfn></dt>
<dt><dfn>walletAddress</dfn></dt>
<dd>
The URL of the monetized document.
The wallet address being paid by this session.
</dd>
</dl>
</section>
Expand Down
12 changes: 12 additions & 0 deletions specification/flows/section/storage.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,12 @@ <h3>Storage operations</h3>
<li>Set |storage|'s {{Storage/wallet}} to |walletAddressDetails|.</li>
<li>[=Persist storage=] with |storage|.</li>
</ol>
<p class="note">
Each invocation of this algorithm establishes a new wallet connection. Implementations
that track per-connection payment history SHOULD associate sessions and payments with
the credential record created during this connection, so that balance computations are
scoped to the active connection only.
</p>
</div>

<div class="algorithm">
Expand Down Expand Up @@ -166,6 +172,12 @@ <h3>Storage operations</h3>
<li>[=Persist storage=] with |storage|.</li>
</ol>
<p class="note">Removes all wallet-related state (grant tokens, authentication keys, wallet address details). Budget limits MAY be retained; implementations can also clear {{Storage/maxRateOfPay}} if the user requests a full reset.</p>
<p class="note">
Implementations that track payment history SHOULD treat each wallet connection as an
independent scope. When a user disconnects and later reconnects (even to the same wallet address),
the new connection starts with a fresh spending balance. Previous connection data MAY be
retained for historical display but MUST NOT affect the active connection's balance computation.
</p>
</div>

<div class="algorithm">
Expand Down