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

Update of PMI spec #16

Merged
merged 7 commits into from
Nov 28, 2016
Merged

Update of PMI spec #16

Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1d037d2
Update of PMI spec
ianbjacobs Nov 16, 2016
0f15f7d
Editorial fixes
ianbjacobs Nov 16, 2016
7c61d2f
Editorial: put code it its own <pre>.
ianbjacobs Nov 17, 2016
ca1484a
Small editorial tweak
ianbjacobs Nov 17, 2016
48e22b6
Add link to issue 17
ianbjacobs Nov 17, 2016
5488dee
Added link to issue 18 (more on URL constraint issues)
ianbjacobs Nov 17, 2016
2839637
Try to refine filter description
ianbjacobs Nov 18, 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
92 changes: 64 additions & 28 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@
<section id='abstract'>
<p>
The Payment Request API [[!PAYMENT-REQUEST-API]] requires that merchants supply a list
of identifiers for supported payment methods. This document defines those identifier
of identifiers for supported payment methods. This specification defines those identifier
strings and how they are created.
</p>
</section>
Expand All @@ -87,11 +87,17 @@
<section class='informative'>
<h2>Introduction</h2>
<p>
One of the principles of the PaymentRequest API is that merchants must know how to accept payments from the payment methods that they claim to support.
This allows the API to abstract away the details of specific payment methods and to add new ones over time without changing the API specification.
To use Payment Request API, merchants (or their service
providers) must know how to handle payment method
specific data for those methods they claim to accept.
This allows the API to abstract away the details of specific
payment methods and to add new ones over time without
changing the API specification.
</p>
<p>
As part of the paymentRequest() call, the web page provides an array of strings that identify the supported payment methods. This document defines those strings.
As part of using Payment Request API, the Web page provides
an array of strings that identify accepted payment methods.
This specification defines those strings.
</p>
</section>

Expand All @@ -105,19 +111,28 @@ <h2>Dependencies</h2>
</section>

<section>
<h2>Payment Method Identifier</h2>
<p>
The <dfn>Payment Method Identifier</dfn> is a string that uniquely identifies a payment method that a user can use to complete a transaction. For example, Visa, MasterCard, and American Express are payment methods used in some countries.
</p>
<h2>URLs as Payment Method Identifiers</h2>
<p>When the party
responsible for a payment method wishes to publish
machine-readable information associated with the payment
method, it does so with a URL.
This URL approach offers at least two benefits: identifier
decentralization and origins as a trust mechanism.
In particular, owners of proprietary payment methods
can use Web servers under their control to publish
security information about authorized payment apps.</p>
<div class="issue" title="Payment method manifest specification in progress">The Web Payments Working Group is developing a payment method manifest specification for the information a payment method owner would want to publish. Payment method identifiers that are URLs will help user agents locate these manifest files, although the exact mechanism is not yet defined. See the early <a href="https://github.com/zkoch/zkoch.github.io/blob/master/payment-manifest.md">Payment Manifest Proposal</a>.
</div>
<div class="issue" title="URL maintenance and performance">Either in the payment method manifest specification or in separate "good practice" documentation, the Working Group should address issues of server performance for payment method identifiers that are URLs. Furthermore, when parties feel they do not need to publish a manifest, we should explain that a manifest with an explicit machine-readable assertion that "any payment app may implement" is preferable to lack of a manifest.
</div>
<section>
<h2>Identifier format</h2>
<p>Payment method identifiers are strings containing a <a>URL</a>. The string MUST be an <a>absolute URL</a>.</p>
<h2>Syntax</h2>
<p>When URLs are used for payment method identifiers they MUST
be absolute URLs including only the schema, origin, and path parts. The URL scheme MUST be <code>https</code>. These URLs MUST NOT include query string parameters or fragment identifiers.</p>
Copy link
Contributor

Choose a reason for hiding this comment

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

Would we ever support other secure schemes (besides https) that are, for example, less susceptible to DDoS attacks? (Like IPFS...)

Do we need to be more generic and just say "secure protocol"?

Also, could we leverage Subresource Integrity somehow to ensure the integrity of the manifest?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I suggest we discuss these at the 17 Nov call (as well as whether the Manifest spec should be included in the PMI Spec).

Copy link
Contributor

Choose a reason for hiding this comment

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

#17

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Hi Adrian,

Per discussion at teleconf today, I've added a link to issue 17 in updates to the pull request.

</section>
<section>
<h2>Identifier equivalence</h2>
<p>When the PaymentRequest API is invoked, the web page provides a list of identifiers for supported payment methods.
The user agent must compare these identifiers to those available to the user and use this to filter what the user
can select. To determine whether two identifiers match, perform the following test:</p>
<h2>Matching</h2>
Copy link
Contributor

Choose a reason for hiding this comment

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

What happens if the URL parser returns failure?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I'd like to hear from user agent implementers.

Copy link
Contributor

Choose a reason for hiding this comment

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

Can we put in a placeholder that shows this behaviour needs to be defined?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Two notes:

  1. I don't think this specification should say how to handle strings that are neither URLs nor W3C short strings. Behavior may vary in different contexts.
  2. Similarly, I don't think this specification should say what to do when there is, for example a 404 on a manifest file.

So if the URL parser fails, it means that the string is not a PMI per this specification (unless it happens to be a W3C short string). When the parser fails, the browser might do any number of things, including (1) still trying to match the string (2) ignoring the string. I think that the PR API spec should speak to this behavior but not the PMI spec.

Copy link
Contributor

Choose a reason for hiding this comment

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

Similarly, I don't think this specification should say what to do when there is, for example a 404 on a manifest file.

I think we'll need to add that when we add the manifest stuff to this spec but happy to do that later when @maxpassion has this ready.

I think that the PR API spec should speak to this behavior but not the PMI spec.

There seems to be a lot of work still required on the show() algorithm to call out to the PMI matching now that we have that defined. https://w3c.github.io/browser-payment-api/#show-method

Happy to move it there but we should probably give the caller some indication that method identifiers have been removed (Step 8) /cc @adrianba @zkoch @rvm4

<p>User agents MUST use the following algorithm to determine whether two payment method identifiers that are URLs match:</p>
<ul>
<li>Let <em>A</em> be the first payment method identifier string and let <em>B</em> be the second payment method
identifier string.</li>
Expand All @@ -131,21 +146,42 @@ <h2>Identifier equivalence</h2>
</section>
</section>

<section class="appendix">
<h2>Issues</h2>

<p>The following issues are tracking aspects of the payment method identifier specification:</p>

<div class="issue" title="Write-up initial proposal for payment app registration spec">
<p>A registration mechanism may exist to install the code for new payment methods into the user agent. This process
would add support for a new payment method to the user agent. This mechanism should be defined in a separate specification.</p>
<p>There is an initial <a href="https://github.com/WICG/paymentrequest/blob/gh-pages/docs/registration.md">outline making a proposal</a>.</p>
</div>

<div class="issue" data-number="3" title="Should a payment method identifier (URL) resolve to a machine readable resource that describes it?">
<p>There is an open issue about whether payment method identifiers should resolve to a resource if they are URLs.</p>
</div>
<section>
<h2>W3C-Defined Strings as Payment Method Identifiers</h2>
<p>W3C expects to publish a small number of payment method
specifications that define abstractions across
similar payment methods (such as credit card payments,
tokenized payments, or credit transfers). W3C expects these
payment methods will be implemented in a wide variety of third party
payment apps. W3C identifies these payment methods with (short) strings; W3C expects to mint these strings in payment method specifications published by the Web Payments Working Group.</p>
<section>
<h2>Syntax</h2>
<p>The syntax of W3C strings used as payment method identifiers is constrained by this regular expression: <code>[a-z0-9-]+</code></p>
Copy link
Contributor

Choose a reason for hiding this comment

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

Put regex in a freestanding code block or at least new line

Copy link
Contributor Author

@ianbjacobs ianbjacobs Nov 17, 2016 •
edited

Choose a reason for hiding this comment

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

I've pushed a change that puts the snippet in a pre

</section>
<section>
<h2>Matching</h2>
<p>For W3C strings, user agents MUST use exact string matching.</p>
</section>
</section>

<section>
<h2>Conditional Matching of Payment Methods</h2>
<p>For some payment methods, merchants may wish to express
that they accept a payment method but only under certain
conditions (e.g., "I only credit cards from brand A and
debit cards from brand B"). The Web Payments Working
Group has discussed several ways to support more sophisticated
matching, including:</p>

<ul>
<li>Parties may mint payment method identifiers to
represent different conditions. This scalable approach may work
well for a small number of independent conditions, but
may not scale well for complex relationships.</li>
<li>Payment methods may define "filters." Merchants provide
Copy link
Contributor

Choose a reason for hiding this comment

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

Maybe mention that filtering is defined in the payment method specs and that support is not a normative requirement of this spec?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I don't think that's necessary because the text says "Payment methods may define filters" which means that the definitions would be in payment method specifications.

Copy link
Contributor

Choose a reason for hiding this comment

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

My point was to be (more) explicit about why there is no filtering behaviour defined here

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Your original suggestion had two parts: (1) filtering is defined in payment method specs. I think that is covered by the existing text. (2) support is not a normative requirement of this spec. I think silence on the matter is equivalent in this case.

Your last comment is to say "why" there is no filtering behavior defined here. Do you have suggested text for that rationale?

Ian

Copy link
Contributor

Choose a reason for hiding this comment

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

Payment methods may define "filters". These are used by callers of the API to affect the payment method identifier matching behavior. No generic filtering mechanism is defined therefor support for filtering is dependent on the level of support that implementations have for the payment methods that define "filters".

filter data as input to the Payment Request API to complement
payment method identifier matching.</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.

👍

</section>
</body>
</html>