-
Notifications
You must be signed in to change notification settings - Fork 22.5k
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.
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
Add landing page for Secure Payment Confirmation (SPC) #28705
Changes from 41 commits
b58c74a
459ea0a
8ffb4ff
193b54f
d9d0ea0
e6cc0fc
e844427
5bce4dc
6e4513f
ca7a90d
a0599f9
667ddff
793c883
19e5352
5b3628e
ef7bdf7
35f0b6a
9910a5d
616b9da
1b668ae
95dd188
5aaa158
0634caa
8163761
d983c41
d15a448
cd28370
35777eb
67cabfd
e6f5be8
96681c0
8b66581
ced78c6
8d96dcf
f328f39
edf999e
d97389e
5493772
a000579
06661bf
44a032a
070769c
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
@@ -0,0 +1,194 @@ | ||||||||||||||||||
--- | ||||||||||||||||||
title: Secure Payment Confirmation | ||||||||||||||||||
slug: Web/API/SPC | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It would be better to have this page at Web/API/Secure_Payment_Confirmation_API |
||||||||||||||||||
page-type: web-api-overview | ||||||||||||||||||
status: | ||||||||||||||||||
- experimental | ||||||||||||||||||
browser-compat: api.SecurePaymentConfirmation | ||||||||||||||||||
--- | ||||||||||||||||||
|
||||||||||||||||||
{{SeeCompatTable}}{{SecureContext_Header}} | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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! |
||||||||||||||||||
|
||||||||||||||||||
The Secure Payment Confirmation API provides a mechanism for strong customer authentication during checkout, thereby protecting against online payment fraud. | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. According to the template for landing pages, we have a short intro paragraph (1 or 2 sentences) and the rest of the overview stuff goes in a section "Concepts and usage" (https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_landing_page_template). So I'd keep this paragraph, then have the |
||||||||||||||||||
|
||||||||||||||||||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The second sentence here is long and complicated. Consider list-formatting to make things easier to read?
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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:
It should also IMO walk through a high-level description of the flow here, which is AFAICT:
|
||||||||||||||||||
|
||||||||||||||||||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. |
||||||||||||||||||
|
||||||||||||||||||
![SPC transaction dialog](spc-dialog.png) | ||||||||||||||||||
|
||||||||||||||||||
Selecting "Verify" initiates a Web Authentication flow. When the user successfully authenticates (e.g., using biometric authenticators on their phone or laptop), the browser passes the data displayed in the dialog to the authenticator, which signs it and returns it as part of the resulting Web Authentication assertion. The assertion can then be passed to the Relying Party for validation. Because the browser passes the displayed data directly to the authenticator (with no JavaScript code able to alter the data), the Relying Party can have high confidence that the user consented to the displayed transaction data. | ||||||||||||||||||
|
||||||||||||||||||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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." |
||||||||||||||||||
|
||||||||||||||||||
### Payment request method | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This should live under a "### Extensions to other interfaces", and should have links to the interfaces that are extended (e.g. Maybe something like:
|
||||||||||||||||||
|
||||||||||||||||||
Secure Payment Confirmation leverages underlying capabilities of the Payment Request API. The standardized payment method identifier for the Secure Payment Confirmation payment handler is `secure-payment-confirmation`. | ||||||||||||||||||
|
||||||||||||||||||
### 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. |
||||||||||||||||||
|
||||||||||||||||||
1. When the Relying Party opts in, allows entities other than the Relying Party to initiate a payments authentication ceremony with the Relying Party's credentials. SPC decouples the authentication ceremony from validation of the authentication results. This allows merchants (or their payment service providers in a cross-origin iframe) to retain control over the user experience of authentication, without forwarding the user (via a redirect) to another Website or mobile app. If the Relying Party is the bank, for example, this enables a merchant to manage the user experience of authentication, while the bank can still validate the results of the authentication. Communication between parties (of credentials and authentication results) typically happens over payment system-specific rails such as EMV® 3-D Secure. | ||||||||||||||||||
2. Enforces that the User Agent appropriately communicates to the user that they are authenticating a transaction and the transaction details. Those details are then included in the assertion signed by the authenticator. | ||||||||||||||||||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm unclear what this note refers to. Is it point 3 above? If it is preferred "where available", then why not document that as the primary name? What does "where available" mean, how am I to know where it is available? |
||||||||||||||||||
|
||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Also, after |
||||||||||||||||||
## Examples | ||||||||||||||||||
|
||||||||||||||||||
### Creating a credential | ||||||||||||||||||
|
||||||||||||||||||
Creating a credential in Secure Payment Confirmation is done by the same `navigator.credentials.create` call as with Web Authentication, but with a `payment` extension specified. | ||||||||||||||||||
|
||||||||||||||||||
```js | ||||||||||||||||||
const publicKey = { | ||||||||||||||||||
challenge: Uint8Array.from(randomStringFromServer, (c) => c.charCodeAt(0)), | ||||||||||||||||||
|
||||||||||||||||||
rp: { | ||||||||||||||||||
name: "Fancy Bank", | ||||||||||||||||||
}, | ||||||||||||||||||
|
||||||||||||||||||
user: { | ||||||||||||||||||
id: Uint8Array.from(userId, (c) => c.charCodeAt(0)), // Assuming that userId is ASCII-only | ||||||||||||||||||
name: "[email protected]", | ||||||||||||||||||
displayName: "Jane Doe", | ||||||||||||||||||
}, | ||||||||||||||||||
|
||||||||||||||||||
pubKeyCredParams: [ | ||||||||||||||||||
{ | ||||||||||||||||||
type: "public-key", | ||||||||||||||||||
alg: -7, // "ES256" | ||||||||||||||||||
}, | ||||||||||||||||||
{ | ||||||||||||||||||
type: "public-key", | ||||||||||||||||||
alg: -257, // "RS256" | ||||||||||||||||||
}, | ||||||||||||||||||
], | ||||||||||||||||||
|
||||||||||||||||||
authenticatorSelection: { | ||||||||||||||||||
userVerification: "required", | ||||||||||||||||||
residentKey: "required", | ||||||||||||||||||
authenticatorAttachment: "platform", | ||||||||||||||||||
}, | ||||||||||||||||||
|
||||||||||||||||||
timeout: 60000, // 1 minute | ||||||||||||||||||
|
||||||||||||||||||
extensions: { | ||||||||||||||||||
payment: { | ||||||||||||||||||
isPayment: true, | ||||||||||||||||||
}, | ||||||||||||||||||
}, | ||||||||||||||||||
}; | ||||||||||||||||||
|
||||||||||||||||||
navigator.credentials | ||||||||||||||||||
.create({ publicKey }) | ||||||||||||||||||
.then((newCredentialInfo) => { | ||||||||||||||||||
// Send new credential info to server for verification and registration. | ||||||||||||||||||
}) | ||||||||||||||||||
.catch((err) => { | ||||||||||||||||||
// No acceptable authenticator or user refused consent. Handle appropriately. | ||||||||||||||||||
}); | ||||||||||||||||||
``` | ||||||||||||||||||
|
||||||||||||||||||
### Creating a credential in a cross-origin iframe | ||||||||||||||||||
|
||||||||||||||||||
SPC allows a credential to be created in a cross-origin iframe (e.g., if `merchant.com` embeds an iframe from `bank.com`). This is intended to support the following flow: | ||||||||||||||||||
|
||||||||||||||||||
As part of a transaction, the Relying Party (e.g., a bank) authenticates the account holder through some mechanism other than SPC (e.g., by using a one-time passcode or some other mechanism). The Relying Party then offers the user the option of registering an SPC credential to streamline future transactions. The user registers an SPC credential with the Relying Party. | ||||||||||||||||||
|
||||||||||||||||||
In order for these steps to happen in the merchant context (that is, without a redirect), the cross-origin iframe must have the 'payment' permission policy set. For example: | ||||||||||||||||||
|
||||||||||||||||||
```html | ||||||||||||||||||
<!-- Assume parent origin is merchant.com --> | ||||||||||||||||||
<!-- Inside this cross-origin iframe, script would be allowed to create a SPC credential for example.org --> | ||||||||||||||||||
<iframe src="https://example.org" allow="payment"></iframe> | ||||||||||||||||||
``` | ||||||||||||||||||
|
||||||||||||||||||
### Authenticating a payment | ||||||||||||||||||
|
||||||||||||||||||
ianbjacobs marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||
An origin may invoke the Payment Request API with the `secure-payment-confirmation` payment method to prompt the user to verify a Secure Payment Confirmation credential created by any other origin. The browser will display a native user interface with transaction details (e.g., the payment currency and amount and the payee origin). | ||||||||||||||||||
|
||||||||||||||||||
> **Note:** Per the Payment Request API, if `PaymentRequest` is used within a cross-origin iframe (e.g., if `merchant.com` embeds an iframe from `psp.com`, and `psp.com` wishes to use `PaymentRequest`), that iframe must have the 'payment' permission policy set. | ||||||||||||||||||
|
||||||||||||||||||
```js | ||||||||||||||||||
const request = new PaymentRequest( | ||||||||||||||||||
[ | ||||||||||||||||||
{ | ||||||||||||||||||
supportedMethods: "secure-payment-confirmation", | ||||||||||||||||||
data: { | ||||||||||||||||||
// List of credential IDs obtained from the Account Provider. | ||||||||||||||||||
credentialIds, | ||||||||||||||||||
|
||||||||||||||||||
// The challenge is also obtained from the Account Provider. | ||||||||||||||||||
challenge: new Uint8Array(randomStringFromServer, (c) => | ||||||||||||||||||
c.charCodeAt(0), | ||||||||||||||||||
), | ||||||||||||||||||
|
||||||||||||||||||
instrument: { | ||||||||||||||||||
displayName: "Fancy Card ****1234", | ||||||||||||||||||
icon: "https://fancybank.com/card-art.png", | ||||||||||||||||||
}, | ||||||||||||||||||
|
||||||||||||||||||
payeeOrigin: "https://merchant.com", | ||||||||||||||||||
|
||||||||||||||||||
timeout: 60000, // 1 minute | ||||||||||||||||||
}, | ||||||||||||||||||
}, | ||||||||||||||||||
], | ||||||||||||||||||
{ | ||||||||||||||||||
total: { | ||||||||||||||||||
label: "Total", | ||||||||||||||||||
amount: { | ||||||||||||||||||
currency: "USD", | ||||||||||||||||||
value: "5.00", | ||||||||||||||||||
}, | ||||||||||||||||||
}, | ||||||||||||||||||
}, | ||||||||||||||||||
); | ||||||||||||||||||
|
||||||||||||||||||
try { | ||||||||||||||||||
// NOTE: canMakePayment() checks only public information for whether the SPC | ||||||||||||||||||
// call is valid. To preserve user privacy, it does not check whether any | ||||||||||||||||||
// passed credentials match the current device. | ||||||||||||||||||
const canMakePayment = await request.canMakePayment(); | ||||||||||||||||||
if (!canMakePayment) { | ||||||||||||||||||
throw new Error("Cannot make payment"); | ||||||||||||||||||
} | ||||||||||||||||||
|
||||||||||||||||||
const response = await request.show(); | ||||||||||||||||||
await response.complete("success"); | ||||||||||||||||||
|
||||||||||||||||||
// response.details is a PublicKeyCredential, with a clientDataJSON that | ||||||||||||||||||
// contains the transaction data for verification by the issuing bank. | ||||||||||||||||||
|
||||||||||||||||||
// send response.details to the issuing bank for verification | ||||||||||||||||||
} catch (err) { | ||||||||||||||||||
// SPC cannot be used; merchant should fallback to traditional flows | ||||||||||||||||||
} | ||||||||||||||||||
``` | ||||||||||||||||||
|
||||||||||||||||||
## Specifications | ||||||||||||||||||
ianbjacobs marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||
|
||||||||||||||||||
{{Specifications}} | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. For this to work you'll need a |
||||||||||||||||||
|
||||||||||||||||||
## Browser compatibility | ||||||||||||||||||
|
||||||||||||||||||
{{Compat}} | ||||||||||||||||||
|
||||||||||||||||||
## See also | ||||||||||||||||||
|
||||||||||||||||||
- [Payment Request API](/en-US/docs/Web/API/Payment_Request_API) | ||||||||||||||||||
- [Payment Method Identifiers](https://www.w3.org/TR/payment-method-id/) | ||||||||||||||||||
- [Web Authentication](/en-US/docs/Web/API/Web_Authentication_API) | ||||||||||||||||||
- [Secure Payment Confirmation Explainer](https://github.com/w3c/secure-payment-confirmation/blob/main/explainer.md) | ||||||||||||||||||
- [Secure Payment Confirmation Scope](https://github.com/w3c/secure-payment-confirmation/blob/main/scope.md) | ||||||||||||||||||
- General [flow diagram for SPC during a payment](https://github.com/w3c/wpsig/blob/gh-pages/spc-general.png) | ||||||||||||||||||
- [Secure Payment Confirmation Test Suite](https://wpt.fyi/results/secure-payment-confirmation?label=master&label=experimental&aligned) | ||||||||||||||||||
- [Chrome developer documentation for SPC](https://developer.chrome.com/articles/secure-payment-confirmation/) | ||||||||||||||||||
- [EMV® 3-D Secure (version 2.3)](https://www.emvco.com/emv-technologies/3-d-secure/) | ||||||||||||||||||
- [EMV® Secure Remote Commerce (version 1.3)](https://www.emvco.com/emv-technologies/secure-remote-commerce/) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.