Skip to content
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

Jump to bottom

Addition of new design considerations #19

Merged
merged 8 commits into from Aug 9, 2016
Merged

Addition of new design considerations #19

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
f172210
Addition of new design considerations
ianbjacobs Aug 5, 2016
d69cc12
Merge remote-tracking branch 'w3c/gh-pages' into gh-pages
ianbjacobs Aug 8, 2016
1d44da0
Small changes based on Shane and AHB feedback
ianbjacobs Aug 8, 2016
aff6560
Small fixes based on AHB comments
ianbjacobs Aug 8, 2016
36802cb
More cleanup and harmonization
ianbjacobs Aug 8, 2016
19e474f
Cleanup language about filtering per AHB
ianbjacobs Aug 8, 2016
32df560
Add pointer to issue 20; add IJ as editor
ianbjacobs Aug 9, 2016
4eb8828
Add pointer to issue 1
ianbjacobs Aug 9, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
106 changes: 50 additions & 56 deletions index.html
View file
Open in desktop
Expand Up @@ -275,18 +275,19 @@ <h3>Decoupling and Trust</h3>
<li> For privacy, the design should limit information about the user's environment available to merchant without user consent. That includes which payment apps the user has registered. For open payment methods, the merchant should not receive information about which payment app the user selected to pay unless the user consents to share that information. See <a href="https://github.com/w3c/browser-payment-api/issues/224">issue 224</a> for discussion about how merchant may track progress of a push payment.</li>
<li> Although decoupling relieves merchants of implementing some aspects of the checkout experience, one consequence is that they give up some degree of control. This was already the case for proprietary payment methods, but for open payment methods such as cards, merchants (or their PSPs) will be entrusting some portion of data collection to third party payment apps, without knowing which app the user will select.</li>
<li> We recognize, therefore, a tension between user preferences (e.g., registered payment apps, ordering of display of payment apps, etc.) and merchant preferences (e.g., control of the user experience previously implemented in a Web page, ordering of payment apps, presence of merchant's own payment app, etc.).</li>
<li> The design should address this tension by enabling the merchant to express preferences for both payment methods and payment apps. The design should not constrain how browsers make us of these preferences, only provide guidance to browser vendors about taking into account both merchant and user preferences.</li>
<li> The design should address this tension by enabling the merchant to express preferences for both payment methods and payment apps. The design should not constrain how browsers make use of these preferences, only provide guidance to browser vendors about taking into account both merchant and user preferences.</li>
<li> Here are preferences the system might support:
<ul>
<li> Accepted payment methods (payment methods the merchant accepts, and no others may be used; part of payment request API)</li>
<li> Preferred payment methods (merchant-specified order part of payment request API)</li>
<li> Recommended payment apps (payment apps the merchant prefers, but others may be used)</li>
<li> Accepted payment apps (payment apps the merchant accepts, and no others may be used). Note that this is the status quo since merchants either accept card information through UI that they control, or they redirect users to payment service providers with whom they have existing relationships. Note that if we allow merchants to restrict payment apps that might end up requiring the customer to install multiple payment apps for the same payment method, which would complicate the user experience for the same payment method.</li>
<li> Accepted payment apps (payment apps the merchant accepts, and no others may be used). Note that this is the status quo since merchants either accept card information through UI that they control, or they redirect users to payment service providers with whom they have existing relationships. Note that if we allow merchants to restrict payment apps that might end up requiring the customer to register multiple payment apps for the same payment method, which would complicate the user experience for the same payment method.</li>
</ul>
</li>
<li> The browser uses this information in conjunction with user preferences to:
<ul>
<li> Filter matching payment apps (in the case of accepted payment apps)</li>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

matching payment apps are also filtered based on accepted payment methods

<li> Display matching payment apps (according to matching payment methods, according to merchant accepted payment method order)</li>
<li> Display matching payment apps (according to matching payment methods, expressed as merchant preferred order)</li>
<li> Display recommended payment apps (according to merchant recommended payment app order)</li>
</ul>
</li>
Expand All @@ -301,7 +302,7 @@ <h3>Registration and Unregistration</h3>
<li> When the merchant recommends a payment app and the user selects it, registration can happen in that moment without additional user action.</li>
<li> When the browser recommends a payment app and the user selects it, registration can happen in that moment without additional user action. (There is an expectation that the display of browser-recommended apps will differ from the display of merchant-recommended apps).</li>
<li> When the user installs native payment app, registration can happen as part of the app installation process.</li>
<li> Users visiting a Web site (e.g., merchant or bank) may wish to explicitly register a payment app outside of the context of checkout.</li>
<li> Users visiting a Web site (e.g., merchant or bank) may be invited to register a payment app outside of the context of checkout.</li>
</ul>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

<li>        Users visiting a Web site (e.g., merchant or bank) may wish 
to explicitly register payment apps unrelated to a specific checkout 
or payment.</li>

</li>
<li>
Expand All @@ -323,14 +324,13 @@ <h3>Payment App Identification</h3>
<li> The origin information could enable browsers to provide the user with useful services when the user is browsing a site with the same origin (e.g., putting that payment app at the top of a list or otherwise highlighted).</li>
<li> For a "proprietary" payment method with an associated origin, the browser can do some (security) checks by comparing the origin of the payment method and the payment app.</li>
</ul>
<li>
<li> A PAI should allow for granularity (e.g., payment app versioning); we should consider URLs.</li>
</ul>
</section>
<section>
<h3>Payment App Matching</h3>
<ul>
<li>When the user invokes the Payment Request API (by, for example, "pushing the Buy button"), the user agent
<li>When the user invokes the Payment Request API (e.g., by "pushing the Buy button"), the user agent
computes the intersection between merchant-accepted payment methods and user-registered payment methods. It
does this by comparing Payment Request API data (from the payee) and data provided during registration,
invoking the comparison algorithm defined in the Payment Method Identifier specification. The result is a list of
Expand All @@ -342,38 +342,46 @@ <h3>Payment App Matching</h3>
relevant for a transaction but that the user has not yet registered or enabled.
<p class="note" title="Browser selection features not in scope">The user agent may offer features to facilitate selection (e.g., launch a chosen payment app or option every time the
user wants to pay at a given Web site); those features lie outside the scope of this specification.</p></li>
<li>The user selects a payment option to make a payment. If the user selected a recommended payment app, behavior
depends on whether the payment app is unregistered or registered.</li>
<li>The user selects a payment option to make a payment. The user may also select a recommended payment app.</li>
</ul>
</section>
<section>
<h3>User Experience</h3>
<ul>
<li>The system should minimize user interaction for payment app registration, payment app selection, and payment credentials selection. Ideas include:
<ul>
<li>When only one payment app matches, the browser does not require user selection to launch it.</li>
<li>The browser displays payment options for direct selection by the user, avoiding the need for the user to make a second selection within the payment app context. The payment app provides the browser with sufficient information to display payment options. It is still possible to launch the payment app upon selection of a payment option, and in some cases the payment app may return a response without further user interaction, depending on the nature of the payment method.</li>
</ul>
</li>
<li>It is likely that this specification will include <em>guidance</em> rather than requirements about specific user experience optimizations.</li>
</ul>
</section>
<section>
<h3>Payment App Invocation and Response</h3>
<ul>
<li>Based on information provided at registration, the user agent "launches" the payment app and provides it with
input data drawn from the Payment Request API.</li>
<li>This specification defines an HTTP-based mechanism for providing input data to the payment app. In some
systems, payment apps may bypass this mechanism entirely, but that behavior lies outside the scope of this
specification.</li>
<li>The user may interact with the payment app in a variety of ways to authorize payment, cancel the transaction,
or carry out other activities supported by the payment app. This specification does not address payment app
behavior other than accepting requests and returning responses to the user agent.</li>
<li>This specification defines a means for the user agent to receive a response asynchronously once the user has
authorized payment. The response becomes the response of the Payment Request API.</li>
</ul>
</section>
<section>
<h3>User Experience</h3>
<ul>
<li>The system should minimize user interaction for payment app registration, payment app selection, and payment credentials selection.</li>
</ul>
</section>
<section>
<h3>Network Considerations</h3>
<ul>
<li>This specification only describes communication between the user agent and the payment app. This includes an
asynchronous mechanism for a payment app to return a payment response to the user agent. This specification
does not (yet) address scenarios where the user agent does not receive the response (e.g., due to a crash or
network outage). Question: Should we recommend asynchronous communication between payment app and servers it talks to? See <a href="https://github.com/w3c/browser-payment-api/issues/224">issue 224</a>.</li>
<li>This specification only describes communication between the
user agent and the payment app. This includes an
asynchronous mechanism for a payment app to return a payment
response to the user agent. This specification does not
(yet) address scenarios where the user agent does not
receive the response (e.g., due to a crash or network
outage). Network failure may be especially problematic in the
case of a push payment; see <a href="https://github.com/w3c/browser-payment-api/issues/224">issue 224</a>, and so the Working Group is considering whether the specification should include a standard way to learn how to query a component for payment state information. For example, many systems use backchannel communications, so one idea is for the payee to provide a callback URL. This would allow (but not require) the payment app to communicate with the payee server until such time as all parties are satisfied they share the same view of the payment response. An alternative would be to provide the payment app and the user agent a channel so that communication continues until all aprties are satisfied they share the same view of the payment response. This might involve caching payment responses.</li>
</ul>
</li>
<li>This specification does not address communication between the payee server and the payee Web app, or between
the payment app and other parties (e.g., the payment app distibutor, or directly to the merchant).</li>
</ul>
Expand Down Expand Up @@ -432,7 +440,12 @@ <h3>Payment App Selection States</h3>
The Working Group has not yet agreed that the system should support recommended payment apps.
Inclusion might involve small changes to payment request API.</p>
</dd>

<dt><dfn id="dfn-accepted-payment-app">accepted payment app</dfn></dt>
<dd>a payment app accepted by the payee. When the payee specifies one or more accepted payment apps, this is a signal that the payee <em>only</em> accepts these payment apps, and thus any matching is limited to these payment apps.
<p class="issue" title="Accepted Payment Apps is still under discussion">
The Working Group has not yet agreed that the system should support accepted payment apps.
Inclusion might involve small changes to payment request API.</p>
</dd>
<dt><dfn id="dfn-displayed-payment-app">displayed payment app</dfn></dt>
<dd>A <a>matching payment app</a> or <a>recommended payment app</a> with at least one selectable payment option (i.e. presented by the browser for user selection).</dd>

Expand Down Expand Up @@ -509,11 +522,15 @@ <h2>Payment App Registration, Updates and Unregistration</h2>
<p>Payment apps are registered with the user agent through a call to the <code>register()</code> method of the API.
The input to the registration process consists of:</p>
<ol>
<li>a <code>request_url</code> which uniquely identifies the app and is
the endpoint for the user agent to submit payment requests</li>
<li>a <code>payment_app_id</code>, a URL that identifies the app.</li>
<li>a <code>request_url</code> which identifies the
endpoint where the user agent submits payment requests.</li>
<li>a sequence of <code>PaymentOption</code>
dictionaries to provide information displayed to the user to facilitate payment app selection.</li>
</ol>



<section>
<h3>The PaymentOption dictionary</h3>
<pre class="idl">
Expand Down Expand Up @@ -544,22 +561,23 @@ <h3>The PaymentOption dictionary</h3>
<section>
<h3>PaymentApp.register()</h3>
<p>
The <code><dfn>register</dfn></code> method may be called if the web page wishes to register a
payment app with the <a>user agent</a>, update the registered information about an already registered
payment app or unregister a payment app.
The <code><dfn>register</dfn></code> method is used to register, update, or unregister a payment app with a <a>user agent</a>.
</p>
<p>
Payment apps are uniquely identifed by their <code>request_url</code>. To update the payment options
Payment apps are uniquely identifed by their <code>payment_app_id</code>. To update the payment options
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was there a decision to change this that I missed?

offered by a registered payment app, a website calls <code>register()</code> using the same
<code>request_url</code> as was used when registering the app and pass in the new sequence of options. To
<code>payment_app_id</code> as was used when registering the app and pass in the new sequence of options. To
unregister a payment app the website calls <code>register()</code> with an empty sequence of options.
</p>
<pre class="idl">
partial interface PaymentApp {
static Promise&lt;void&gt; register (URLString request_url, sequence&lt;PaymentOption&gt; payment_options);
static Promise&lt;void&gt; register (URLString payment_app_id, URLString request_url, sequence&lt;PaymentOption&gt; payment_options);
};
</pre>
<dl>
<dt><code>payment_app_id</code> parameter</dt>
<dd>An identifier for the payment app. If a payment app is already installed with the same <code><a>request_url</a></code>
the registered payment options will be replaced with the new sequence of options provided.</dd>
<dt><code>request_url</code> parameter</dt>
<dd>
<p>
Expand All @@ -573,11 +591,6 @@ <h3>PaymentApp.register()</h3>
to register the payment app.
</p>
<p class="note" title="Origin for native apps">Native apps could be registered from Web pages, thus allowing the association of an origin to a native app.</p>
<p>
The <code><a>request_url</a></code> is also the unique identifier for the payment app.
If a payment app is already installed with the same <code><a>request_url</a></code>
the registered payment options will be replaced with the new sequence of options provided.
</p>
</dd>
<dt><code>payment_options</code> parameter</dt>
<dd>
Expand Down Expand Up @@ -642,17 +655,13 @@ <h3>PaymentApp.register()</h3>
});
</pre>
</section>
<p class="issue" title="Invocation model">
We need to confirm the registration approach we wish to take. HTTP or JavaScript? What is the role of service
workers?
</p>
<p class="issue" title="Registration of native payment apps?">
What, if anything, should we say about registering native payment apps?
</p>
</section>
<section id="matching">
<h2>Payment App Matching</h2>
<div class="issue" title="Dependancy on Payment Method Identifiers spec">
<div class="issue" title="Dependency on Payment Method Identifiers spec">
<p>
We anticipate that the Payment Method Identifier specification will define the PMI matching algorithm. This
specification will explain how to invoke that algorithm using data available from the Payment Request API input
Expand Down Expand Up @@ -834,22 +843,7 @@ <h3>Payment App Invocation</h3>
that is set in the response.
</p>
<div class="issue" data-number="141" title="Handling network and other failures">
<p>Communication mail fail at various points in the flow, including between server and payment app:</p>
<ul>
<li>Payment server to payment app</li>
<li>Payment app to user agent</li>
<li>Payee Web app to payee server</li>
</ul>
<p>
What sort of guarantees should we endeavor to provide, if any, for any of these points in the flow? If, for examle, a proof of payment is lost
along the communication flow, then, for instance, a merchant might not shiop goods. Some observations:
</p>
<ul>
<li>Today, backchannel communications are often used (e.g., between payment server and payee server).</li>
<li>The payee could provide a callback URL (identified as such in a standard way). This would allow (but not require) the payment app to communicate with the payee server until such time as all parties are satisfied they share the same view of the payment response.</li>
<li>An alternative is to ensure that the payment app and the user agent have a channel so that communication continues until all aprties are satisfied they share the same view of the payment response. This might involve caching payment responses.</li>
<li>What happens in Payment Request API if the user agent closes before the promise resolves?</li>
</ul>
<p>Communication mail fail at various points in the flow; see design considerations for some ideas for managing this.</p>
</div>
</section>
<section>
Expand Down