Add landing page for Secure Payment Confirmation (SPC) #28705
Conversation
ianbjacobs
requested review from
sideshowbarker
and removed request for
a team
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
Argh. I made a mistake and put the image in the wrong directory. I'll try to fix that but welcome help! |
|
Preview URLs Flaws (1)URL:
External URLs (9)URL:
(comment last updated: 2023-10-16 17:49:29) |
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Thanks @sideshowbarker! I read your comments and made some minor punctuation changes (but not all of the ones you suggested; I think there is some room for style differences here. :) |
| browser-compat: api.SecurePaymentConfirmation | ||
| --- | ||
|
|
||
| {{SeeCompatTable}}{{SecureContext_Header}} |
There was a problem hiding this comment.
We need a sidebar for this, but I don't know exactly what needs to be done. Perhaps @hamishwillee and @wbamberg know better.
There was a problem hiding this comment.
We need a sidebar for this, but I don't know exactly what needs to be done. Perhaps @hamishwillee and @wbamberg know better.
It’d need a new key/value added to https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json.
There was a problem hiding this comment.
We have a problem with this API because AFAICT it doesn't define any things which we have reference pages for, and we don't currently have any guide pages for it, so although we can formally define a sidebar in groupdata.json, it will only contain 1 page!
|
Hello all, is there anything I can do to help with this pull request? Thanks! |
Sorry @ianbjacobs I did have some comments but didn't finish my review. But I will do it now. |
|
@wbamberg, thank you. I don't mean to rush, only to see if I can be helpful. Thanks for your review! |
There was a problem hiding this comment.
I'm sorry to take so long to review this. I know it's already had some review from a couple of MDN maintainers, so if they don't agree with my comments here I'm happy to defer.
I've left some detailed comments which are made under the assumption that we will want to keep this landing page, but I'd question whether we should document SPC as its own API on MDN.
MDN's model for Web APIs is that we have:
- pages for concrete things like interfaces and their methods, and sometimes for dictionaries.
- landing pages for APIs which are more abstract collections of these concrete things.
Landing pages have a conceptual overview of the API, as you have here, but are also navigational pages containing links to the concrete web platform features that implement them.
This model works well for specs that are relatively large and self-contained, but it doesn't work so well for small specs that extend (and only make sense in the context of) other specs. So while historically APIs usually do map to specifications, they don't always. For example, we recently reworked/rewrote the Performance API pages, (openwebdocs/project#62) and in the process merged landing pages for all the Performance API specs, and the docs are more coherent for it.
In this case, if I understand it right, it looks like the API consists of extensions to two other APIs, the Payment Request API and the Web Authentication API. But it only defines one thing that could get its own page on MDN - the SecurePaymentConfirmationRequest dictionary.
This gives us some structural problems if we want to represent it as its own API, for example that because of the model we have for sidebars, the sidebar would only contain one page (the page for SecurePaymentConfirmationRequest), so wouldn't be very useful for navigation.
But I think more important is the fact that this is so entwined with the Payment Request and Web Authentication APIs that it's not possible for someone to understand it without understanding that API, which makes it hard to understand it when it's presented as a standalone thing. Presenting it as an extension to those APIs would make the docs more coherent.
Whether or not we wanted to keep this as a separate landing page, there are some other docs we'd need on MDN for web developer to be able to use it:
- we should have a page for
SecurePaymentConfirmationRequest - we should update https://developer.mozilla.org/en-US/docs/Web/API/PaymentRequest/PaymentRequest#supportedmethods to list
secure-payment-confirmationas a value forsupportedMethods - we should update https://developer.mozilla.org/en-US/docs/Web/API/PaymentRequest/PaymentRequest#data to say that when the method is
secure-payment-confirmation, thendatashould be aSecurePaymentConfirmationRequestinstance - we should update https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions to add a bit on
payment - we should somewhere talk about the how covering what a web developer needs to to to add SPC to a site, talking explicitly about which concrete APIs to call when and how theu knit together. Currently https://w3c.github.io/secure-payment-confirmation/#sctn-sample-scenarios looks quite useful, and it wuould be great to have a version of this on MDN. We could make that a separate guide page like "Using the Secure Payment Confirmation API".
I don't know if you are planning to add these docs. I'm happy to help but would surely need help with some of the technical side.
If we don't want to keep this as a separate landing page, then we could repurpose it as part of (5) above, and keep it under https://developer.mozilla.org/en-US/docs/Web/API/PaymentRequest/.
| @@ -0,0 +1,194 @@ | |||
| --- | |||
| title: Secure Payment Confirmation | |||
There was a problem hiding this comment.
| title: Secure Payment Confirmation | |
| title: Secure Payment Confirmation API |
| @@ -0,0 +1,194 @@ | |||
| --- | |||
| title: Secure Payment Confirmation | |||
| slug: Web/API/SPC | |||
There was a problem hiding this comment.
It would be better to have this page at Web/API/Secure_Payment_Confirmation_API
|
|
||
| The Secure Payment Confirmation API provides a mechanism for strong customer authentication during checkout, thereby protecting against online payment fraud. | ||
|
|
||
| To protect against online payment fraud, it is common to authenticate the account holder. Strong authentication lowers the risk of fraud, but increases the likelihood that friction during checkout will lead to shopping cart abandonment. Banks, merchants, payment services providers, and other entities in a payments ecosystem therefore consider a number of factors when deciding what type and strength of authentication to use for each transaction, including the amount, the items being purchased, the user's payment history, which party bears liability in the case of fraud, and regulatory requirements (such as [European Payment Services Directive 2](<https://en.wikipedia.org/wiki/Payment_Services_Directive#Revised_Directive_on_Payment_Services_(PSD2)>) requirements for strong customer authentication and evidence of user consent). |
There was a problem hiding this comment.
The second sentence here is long and complicated. Consider list-formatting to make things easier to read?
| To protect against online payment fraud, it is common to authenticate the account holder. Strong authentication lowers the risk of fraud, but increases the likelihood that friction during checkout will lead to shopping cart abandonment. Banks, merchants, payment services providers, and other entities in a payments ecosystem therefore consider a number of factors when deciding what type and strength of authentication to use for each transaction, including the amount, the items being purchased, the user's payment history, which party bears liability in the case of fraud, and regulatory requirements (such as [European Payment Services Directive 2](<https://en.wikipedia.org/wiki/Payment_Services_Directive#Revised_Directive_on_Payment_Services_(PSD2)>) requirements for strong customer authentication and evidence of user consent). | |
| To protect against online payment fraud, it is common to authenticate the account holder. Strong authentication lowers the risk of fraud, but increases the likelihood that friction during checkout will lead to shopping cart abandonment. Banks, merchants, payment services providers, and other entities in a payments ecosystem therefore consider a number of factors when deciding what type and strength of authentication to use for each transaction, including: | |
| - the amount | |
| - the items being purchased | |
| - the user's payment history | |
| - which party bears liability in the case of fraud | |
| - regulatory requirements (such as [European Payment Services Directive 2](<https://en.wikipedia.org/wiki/Payment_Services_Directive#Revised_Directive_on_Payment_Services_(PSD2)>) requirements for strong customer authentication and evidence of user consent). |
|
|
||
| A number of mechanisms are used in combination for strong authentication, including passwords, one-time SMS codes, mobile applications, and Web Authentication. Each one has its advantages and disadvantages. For example, one-time SMS codes are now familiar to users but can involve usability issues (such as device unavailability) and security vulnerabilities. Web Authentication offers better security and is available in all major browsers and all modern mobile devices and computers. However, Web Authentication alone does not provide evidence of user consent to make a payment. | ||
|
|
||
| Secure Payment Confirmation (SPC) is designed to enable streamlined strong customer authentication (SCA) in a variety of payment systems, and to provide cryptographic evidence that the user has consented to the terms of a transaction. When the API is called, the browser displays elements of the transaction in a dialog box: the name of the merchant, payment instrument, and amount and currency of payment. For example, here is the Chrome transaction dialog for SPC: |
There was a problem hiding this comment.
Where we say "the API is called" here, which API, and what calls it?
I think it might be helpful to describe the complete flow here with named and defined entities.
|
|
||
| ### Web authentication extension | ||
|
|
||
| Secure Payment Confirmation defines a Web Authentication extension, `payment`, which adds three payments-specific capabilities on top of traditional Web Authentication: |
There was a problem hiding this comment.
I'd expect this and the next few paragraphs to live in a new section of https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions#available_extensions.
The purpose of this section is really to link to pages giving the details, not to provide the details itself.
|
|
||
| The Secure Payment Confirmation API provides a mechanism for strong customer authentication during checkout, thereby protecting against online payment fraud. | ||
|
|
||
| To protect against online payment fraud, it is common to authenticate the account holder. Strong authentication lowers the risk of fraud, but increases the likelihood that friction during checkout will lead to shopping cart abandonment. Banks, merchants, payment services providers, and other entities in a payments ecosystem therefore consider a number of factors when deciding what type and strength of authentication to use for each transaction, including the amount, the items being purchased, the user's payment history, which party bears liability in the case of fraud, and regulatory requirements (such as [European Payment Services Directive 2](<https://en.wikipedia.org/wiki/Payment_Services_Directive#Revised_Directive_on_Payment_Services_(PSD2)>) requirements for strong customer authentication and evidence of user consent). |
There was a problem hiding this comment.
IMO this does a good job of explaining the "what" and "why", but doesn't really connect the "how" to concrete web platform features, which is I think is necessary if developers will be able to use it. I think a detailed "How to" should be in a separate guide page, but this section should give an overview. In particular I think it should cover:
- that the API consists of extensions to the Web Authentication API and the Payment Request API
- that the extension points are:
- a new
paymentWeb Authentication extension. - a new
secure-payment-confirmationvalue for thesupportedMethodsvalue passed to thePaymentRequest()constructor, along with a correspondingdatavalue which is defined as theSecurePaymentConfirmationRequestdictionary.
- a new
It should also IMO walk through a high-level description of the flow here, which is AFAICT:
- when the user tries to buy something, if they are not yet registered for SPC, then the Web Auth
paymentextension is used to create a credential that can later be used in the SPC flow itself. - subsequently, when a registered user tries to buy something, the
secure-payment-confirmationvalue is used in the Payment Request API to trigger a secure payment confirmation flow, without the user having to reauthenticate.
|
|
||
| Thus, SPC builds on Web Authentication to enable sites to perform streamlined strong authentication and provide evidence of user consent. SPC will typically be used as part of the authentication framework of a given payment system. For example, SPC is supported by both EMV® 3-D Secure (version 2.3.1) and EMV® Secure Remote Commerce (version 1.3) but is designed to work with a wide variety of payment types, including "push payments" like direct credit transfers and wallet payments. | ||
|
|
||
| ## Interfaces |
There was a problem hiding this comment.
See https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_landing_page_template#interfaces, this section should first list interfaces defined in this API. Since there aren't any, we should probably say something like "This API does not define any new interfaces."
|
|
||
| ## Interfaces | ||
|
|
||
| ### Payment request method |
There was a problem hiding this comment.
This should live under a "### Extensions to other interfaces", and should have links to the interfaces that are extended (e.g. PaymentRequest)and to the parts of that interface that are extended (e.g. supportedMethods).
Maybe something like:
- `secure-payment-confirmation` payment method identifier
- : Adds a new payment method identifier, `secure-payment-confirmation`, for the [`supportedMethods`](/en-US/docs/Web/API/PaymentRequest/PaymentRequest#supportedmethods)) parameter to the [`PaymentRequest()` constructor](/en-US/docs/Web/API/PaymentRequest/PaymentRequest).
- `payment` Web Authentication extension
- : Add a new [Web Authentication extension](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions) named [`payment`](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions#payment).
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} |
There was a problem hiding this comment.
For this to work you'll need a spec-urls front matter key with a value of https://w3c.github.io/secure-payment-confirmation.
| 3. Allows calling `navigator.credentials.create` in a cross-origin iframe, as long as a "payment" permission policy is set on the iframe. | ||
|
|
||
| > **Note:** This ability is now part of WebAuthn Level 3, where it uses the "publickey-credential-create" permission policy instead. Developers are encouraged to use that where available, instead of relying on SPC's "payment" permission. | ||
|
|
There was a problem hiding this comment.
Also, after ## Interfaces we should have ## Dictionaries, which should contain a link to the presently unwritten reference page at https://developer.mozilla.org/en-US/docs/Web/API/SecurePaymentConfirmationRequest.
|
@wbamberg, I first want to thank you for the thorough and thoughtful review. I will take some time to chat with colleagues about the comments and ideas for next steps. Again, much appreciated! |
|
@wbamberg, what would you think about the following alternative approach:
In other words:
I look forward to your suggestions, Ian [1] https://developer.mozilla.org/en-US/docs/Web/Guide |
Hello Ian Sorry for the delay again but I wanted to chat about this with some of the other maintainers, because this is a bit tricky. I think your suggestion is mostly great, but I think it would be better to have the guide (1) be just about SPC and (2) live under https://developer.mozilla.org/en-US/docs/Web/API/Payment_Request_API than under https://developer.mozilla.org/en-US/docs/Web/Guide. The reason for this is is mostly about discoverability: https://developer.mozilla.org/en-US/docs/Web/Guide is a real mess, containing quite a random selection of pages that don't integrate well with other bits of the site. Have a look at the sidebar there to show what I mean. So we're not particularly keen to add new pages there. I think this is coming up against an information architecture problem on MDN: we have, or rather had, a clear model for how to organize Web/API reference docs, but we don't have a good way to organize documentation that cuts across multiple specifications, and our existing model does not work well for small closely related specifications - we just lose coherence by trying to document them all separately, and we don't have a place to document them together. I think eventually we would need to have a better solution here, but for now we are tending to be more loose with the definition of what should be under an "API" on MDN, to allow things from multiple specs to share the same part of the tree. Does that make sense?
We treat dictionaries as interfaces that happen to not have methods. For example: https://developer.mozilla.org/en-US/docs/Web/API/CryptoKeyPair . It's our belief that web developers don't see a meaningful distinction between interfaces and dictionaries. We don't always (or even very often) give WebIDL dictionaries their own pages on MDN, because usually they are only used in one place and it seems clearer and more direct to document them inline. For example, for |
Hi @wbamberg, Let me know if this updated proposal fits with your recommendations. Ian
|
|
I think this is a great plan. Since I'm causing so much extra work, I'm very happy to help out in any way I can: I can review docs and help with MDN-specific conventions but if you like I'm also happy to draft some docs as well. |
|
@wamberg, I think this collaboration is going well, so all is good from my perspective. I will welcome your ongoing review and suggestions. If I do some work on content (and its organization) could I ask for your review of a document (e.g., a set of proposed blobs and where they would go) rather than going straight to a pull request? Once we've ironed out the organizational aspect (including URLs) then I will feel more comfortable with a new pull request. |
|
Based on our discussion, here's a sketch of how the content might be organized: Comments welcome. Once it looks close enough, I can turn it into a multi-document pull request. Cheers! |
I think this looks great. A couple of small comments:
|
|
@wbamberg, I'll continue to develop the multi-file pull request. I propose to close this pull request, create a new (multi-file) pull request, and link to this PR from there. Sound ok? |
Sounds great, thank you @ianbjacobs ! |
Description
This is a landing page for Secure Payment Confirmation (SPC).
Motivation
SPC is already shipping in several browsers and should be documented on MDN.
Additional details
See the pull request for details.
Related issues and pull requests
Relates to #421