attribute EventHandler onmerchantvalidation;

<section data-dfn-for="PaymentRequest" data-link-for="PaymentRequest">

<h2>

<dfn>onmerchantvalidation</dfn> attribute

</h2>

<p data-tests=

"payment-request/onmerchantvalidation-attribute.https.html">

A <a>PaymentRequest</a>'s <a>onmerchantvalidation</a> attribute is an

<a>EventHandler</a> for a <a>MerchantValidationEvent</a> named

"<a>merchantvalidation</a>".

</p>

</section>

<tr>

<td>

<code><dfn>merchantvalidation</dfn></code>

</td>

<td>

<a>MerchantValidationEvent</a>

</td>

<td>

The user agent requires the merchant to perform merchant

validation.

</td>

<td>

<a>PaymentRequest</a>

</td>

</tr>

<section data-dfn-for="MerchantValidationEvent" data-link-for=

"MerchantValidationEvent">

<h2>

<dfn>MerchantValidationEvent</dfn> interface

</h2>

<pre class="idl">

[Constructor(DOMString type, optional MerchantValidationEventInit eventInitDict),

SecureContext, Exposed=Window]

interface MerchantValidationEvent : Event {

readonly attribute USVString validationURL;

void complete(Promise&lt;any&gt; merchantSessionPromise);

};

</pre>

<section>

<h3>

<dfn data-lt=

"MerchantValidationEvent.MerchantValidationEvent()"><code>MerchantValidationEvent</code>

constructor</dfn>

</h3>

<p data-tests=

"MerchantValidationEvent/constructor.https.html, MerchantValidationEvent/constructor.http.html">

The <a data-cite="dom#concept-event-constructor-ext">event

constructing steps</a>, which take a <a>MerchantValidationEvent</a>

<var>event</var>, are as follows:

</p>

<ol class="algorithm">

<li>Let <var>base</var> be the <a data-cite=

"dom#context-object">event</a>’s <a data-cite=

"!html/multipage/webappapis.html#relevant-settings-object">relevant

settings object</a>’s <a data-cite=

"!html/multipage/webappapis.html#api-base-url">API base URL</a>.

</li>

<li>Let <var>input</var> be the empty string.

</li>

<li>If <var>eventInitDict</var> was passed, set <var>input</var> to

the value of <var>eventInitDict</var>["<a>validationURL</a>"].

</li>

<li data-link-for="MerchantValidationEventInit">Let

<var>validationURL</var> be the result of <a data-cite=

"!url#concept-url-parser">URL parsing</a> <var>input</var> and

<var>base</var>.

</li>

<li>If <var>validationURL</var> is failure, throw a

<a>TypeError</a>.

</li>

<li>Initialize <var>event</var>.<a>validationURL</a> attribute to

<var>validationURL</var>.

</li>

<li>Initialize <var>event</var>.<a data-lt=

"mechvalidation.waitForUpdate">[[\waitForUpdate]]</a> to false.

</li>

</ol>

</section>

<section>

<h3>

<dfn>validationURL</dfn> attribute

</h3>

<p>

A <a data-cite="url#concept-url">URL</a> from which a developer can

fetch <a>payment handler</a>-specific verification data. By then

passing that data (or a promise that resolves with that data) to

<a>complete()</a>, the user agent can verify that the payment

request is from a authorized merchant.

</p>

<p>

When getting, returns the value it was <a data-cite=

"dom#inner-event-creation-steps">initialized</a> with.

</p>

</section>

<section>

<h3>

<dfn>complete()</dfn> method

</h3>

<p data-test=

"payment-request/MerchantValidationEvent/complete-method-manual.https.html">

The <a>MerchantValidationEvent</a>'s

<code>complete(<var>merchantSessionPromise</var>)</code> method

MUST act as follows:

</p>

<ol class="algorithm">

<li>Let <var>event</var> be the <a>context object</a>.

</li>

<li>If <var>event</var>'s <a>isTrusted</a> attribute is false, then

<a>throw</a> an "<a>InvalidStateError</a>" <a>DOMException</a>.

</li>

<li>If <var>event</var>.<a data-lt=

"mechvalidation.waitForUpdate">[[\waitForUpdate]]</a> is true, then

<a>throw</a> an "<a>InvalidStateError</a>" <a>DOMException</a>.

</li>

<li>Let <var>request</var> be <var>event</var>'s <a data-cite=

"dom#event-target">target</a>.

</li>

<li>If <var>request</var>.<a>[[\state]]</a> is not

"<a>interactive</a>", then <a>throw</a> an

"<a>InvalidStateError</a>" <a>DOMException</a>.

</li>

<li>If <var>request</var>.<a>[[\updating]]</a> is true, then

<a>throw</a> an "<a>InvalidStateError</a>" <a>DOMException</a>.

</li>

<li>Set <var>event</var>'s <a>stop propagation flag</a> and <a>stop

immediate propagation flag</a>.

</li>

<li>Set <var>event</var>.<a data-lt=

"mechvalidation.waitForUpdate">[[\waitForUpdate]]</a> to true.

</li>

<li>Run the <a>validate merchant's details algorithm</a> with <var>

merchantSessionPromise</var> and <var>request</var>.

</li>

</ol>

</section>

<section>

<h2>

Internal Slots

</h2>

<p>

Instances of <a>MerchantValidationEvent</a> are created with the

internal slots in the following table:

</p>

<table>

<tr>

<th>

Internal Slot

</th>

<th>

Description (<em>non-normative</em>)

</th>

</tr>

<tr>

<td>

<dfn data-lt-nodefault="" data-lt=

"mechvalidation.waitForUpdate">[[\waitForUpdate]]</dfn>

</td>

<td>

A boolean indicating whether an <a>complete()</a>-initiated

update is currently in progress.

</td>

</tr>

</table>

</section>

<section data-dfn-for="MerchantValidationEventInit" data-link-for=

"MerchantValidationEventInit">

<h3>

<dfn>MerchantValidationEventInit</dfn> dictionary

</h3>

<pre class="idl">

dictionary MerchantValidationEventInit : EventInit {

USVString validationURL = "";

};

</pre>

<section>

<h4>

<dfn>validationURL</dfn> member

</h4>

<p>

A URL from which a developer would fetch <a>payment

handler</a>-specific verification data.

</p>

</section>

</section>

</section>

<section>

<h2>

Merchant validation

</h2>

<p>

<dfn data-lt="Validate the merchant">Merchant validation</dfn> is the

process by which a <a>payment handler</a> validates the identity of a

merchant against some <var>value</var> (usually some cryptographic

challenge response). Validated merchants are allowed to interface

with a <a>payment handler</a>. Details of how actual validation is

performed is outside the scope of this specification.

</p>

<p>

It is OPTIONAL for a <a>payment handler</a> to support <a>merchant

validation</a>.

</p>

<p>

For <a>payment methods</a> that support <a>merchant validation</a>,

the user agent runs the <dfn>request merchant validation

algorithm</dfn>. The algorithm takes a <a data-cite=

"webidl#idl-USVString"><code>USVString</code></a>

<var>merchantSpecificURL</var>, provided by the <a>payment

handler</a>:

</p>

<ol class="algorithm">

<li>Let <var>request</var> be the <a>PaymentRequest</a> object that

the user is interacting with.

</li>

<li>Let <var>validationURL</var> be a <a data-cite=

"url#absolute-url-string">absolute URL string</a> from which a

developer can fetch <a>payment handler</a>-specific verification

data.

</li>

<li>

<a>Queue a task</a> on the <a>user interaction task source</a> to

run the following steps:

<ol>

<li>Assert: <var>request</var>.<a>[[\updating]]</a> is false.

</li>

<li>Assert: <var>request</var>.<a>[[\state]]</a> is

"<a>interactive</a>".

</li>

<li>Let <var>eventInitDict</var> be an new

<a>MerchantValidationEventInit</a> dictionary.

</li>

<li data-link-for="MerchantValidationEventInit">Set

<var>eventInitDict</var>["<a>validationURL</a>"] to

<var>validationURL</var>.

</li>

<li>Let <var>event</var> be the result of <a data-cite=

"dom#concept-event-constructor">constructing</a> a

<a>MerchantValidationEvent</a> with "<a>merchantvalidation</a>"

and <var>eventInitDict</var>.

</li>

<li>Initialize <var>event</var>’s <a data-cite=

"dom#dom-event-istrusted"><code>isTrusted</code></a> attribute to

true.

</li>

<li>

<a data-cite="dom#concept-event-dispatch">Dispatch</a>

<var>event</var> to <var>request</var>.

</li>

</ol>

</li>

</ol>

</section>

<section>

<h2>

Validate merchant's details algorithm

</h2>

<p>

The <dfn>validate merchant's details algorithm</dfn> takes a

<a>Promise</a> <var>opaqueDataPromise</var> and a

<a>PaymentRequest</a> <var>request</var>. The steps are conditional

on the <var>opaqueDataPromise</var> settling. If

<var>opaqueDataPromise</var> never settles then the payment request

is blocked. The user agent SHOULD provide the user with a means to

abort a payment request. Implementations MAY choose to implement a

timeout for pending updates if <var>opaqueDataPromise</var> doesn't

settle in a reasonable amount of time. If an implementation chooses

to implement a timeout, they MUST execute the steps listed below in

the "upon rejection" path. Such a timeout is a fatal error for the

payment request.

</p>

<ol class="algorithm">

<li>Set <var>request</var>.<a>[[\updating]]</a> to true.

</li>

<li>

<a>In parallel</a>, disable the user interface that allows the user

to accept the payment request. This is to ensure that the payment

is not accepted until the user interface is updated with any new

details.

</li>

<li>

<a>Upon rejection</a> of <var>opaqueDataPromise</var>:

<ol>

<li>

<a>Abort the update</a> with <var>request</var> and an

"<a>AbortError</a>" <a>DOMException</a>.

</li>

</ol>

</li>

<li>

<a>Upon fulfillment</a> of <var>opaqueDataPromise</var> with value

<var>opaqueData</var>:

<ol>

<li>

<a>Validate the merchant</a> using <var>opaqueData</var>.

</li>

<li>If <var>opaqueData</var> is invalid, as per the validation

rules of the <a>payment handler</a>, <a>abort the update</a> with

<var>request</var> and an appropriate <a data-cite=

"!webidl#dfn-exception">exception</a> and return.

</li>

<li>Otherwise, set <var>request</var>.<a>[[\updating]]</a> to

false.

</li>

<li>Enable the user interface, allowing the request for payment

to proceed.

</li>

</ol>

</li>

</ol>

</section>