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.

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

Closed
wants to merge 42 commits into from
Closed
Show file tree
Hide file tree
Changes from 41 commits
Commits
Show all changes
42 commits
Select commit Hold shift + click to select a range
b58c74a
Create index.md
ianbjacobs Aug 22, 2023
459ea0a
Add image
ianbjacobs Aug 22, 2023
8ffb4ff
Add image link
ianbjacobs Aug 22, 2023
193b54f
Image
ianbjacobs Aug 22, 2023
d9d0ea0
Delete spc-dialog.png
ianbjacobs Aug 22, 2023
e6cc0fc
Change slug
ianbjacobs Aug 22, 2023
e844427
Hopeful markdown fixes.
ianbjacobs Aug 22, 2023
5bce4dc
Trying to fix markdown issues
ianbjacobs Aug 22, 2023
6e4513f
Markdown fixes
ianbjacobs Aug 22, 2023
ca7a90d
Markdown fix
ianbjacobs Aug 22, 2023
a0599f9
More attempts at markdown fixes
ianbjacobs Aug 22, 2023
667ddff
Quote character fixes
ianbjacobs Aug 22, 2023
793c883
Merge branch 'main' into ianbjacobs-spc-1
ianbjacobs Aug 22, 2023
19e5352
Update files/en-us/web/api/spc/index.md
ianbjacobs Aug 22, 2023
5b3628e
Update files/en-us/web/api/spc/index.md
ianbjacobs Aug 22, 2023
ef7bdf7
Update files/en-us/web/api/spc/index.md
ianbjacobs Aug 22, 2023
35f0b6a
Update files/en-us/web/api/spc/index.md
ianbjacobs Aug 22, 2023
9910a5d
Update files/en-us/web/api/spc/index.md
ianbjacobs Aug 22, 2023
616b9da
Update files/en-us/web/api/spc/index.md
ianbjacobs Aug 22, 2023
1b668ae
Update files/en-us/web/api/spc/index.md
ianbjacobs Aug 22, 2023
95dd188
Update files/en-us/web/api/spc/index.md
ianbjacobs Aug 22, 2023
5aaa158
Update files/en-us/web/api/spc/index.md
ianbjacobs Aug 22, 2023
0634caa
Update files/en-us/web/api/spc/index.md
ianbjacobs Aug 22, 2023
8163761
Update files/en-us/web/api/spc/index.md
ianbjacobs Aug 22, 2023
d983c41
Apply suggestions from code review
ianbjacobs Aug 22, 2023
d15a448
Fix line break
ianbjacobs Aug 22, 2023
cd28370
Apply suggestions from code review
ianbjacobs Aug 22, 2023
35777eb
Update files/en-us/web/api/spc/index.md
ianbjacobs Aug 22, 2023
67cabfd
Fix some issues
Josh-Cena Aug 22, 2023
e6f5be8
Update index.md
Josh-Cena Aug 22, 2023
96681c0
Prettify
Josh-Cena Aug 22, 2023
8b66581
No function expressions
Josh-Cena Aug 23, 2023
ced78c6
Intro sentence.
ianbjacobs Aug 23, 2023
8d96dcf
Delete spc-dialog.png
ianbjacobs Aug 23, 2023
f328f39
Add files via upload
ianbjacobs Aug 23, 2023
edf999e
Link to MDN for PR API and WebAuthn
ianbjacobs Aug 23, 2023
d97389e
Apply suggestions from code review
ianbjacobs Aug 23, 2023
5493772
Add BCD key
Josh-Cena Aug 23, 2023
a000579
Merge branch 'mdn:main' into ianbjacobs-spc-1
ianbjacobs Aug 23, 2023
06661bf
editorial
ianbjacobs Aug 23, 2023
44a032a
backticks
ianbjacobs Aug 23, 2023
070769c
Merge branch 'main' into ianbjacobs-spc-1
wbamberg Oct 16, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
194 changes: 194 additions & 0 deletions files/en-us/web/api/spc/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
---
title: Secure Payment Confirmation
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
title: Secure Payment Confirmation
title: Secure Payment Confirmation API

slug: Web/API/SPC
Copy link
Collaborator

Choose a reason for hiding this comment

The 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}}
Copy link
Member

Choose a reason for hiding this comment

The 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.

Copy link
Member

Choose a reason for hiding this comment

The 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.

It’d need a new key/value added to https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json.

Copy link
Collaborator

Choose a reason for hiding this comment

The 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The 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 ## Concepts and usage after it.


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).
Copy link
Collaborator

@wbamberg wbamberg Sep 20, 2023

Choose a reason for hiding this comment

The 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
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).

Copy link
Collaborator

Choose a reason for hiding this comment

The 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:

  • that the API consists of extensions to the Web Authentication API and the Payment Request API
  • that the extension points are:
    • a new payment Web Authentication extension.
    • a new secure-payment-confirmation value for the supportedMethods value passed to the PaymentRequest() constructor, along with a corresponding data value which is defined as the SecurePaymentConfirmationRequest dictionary.

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 payment extension 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-confirmation value is used in the Payment Request API to trigger a secure payment confirmation flow, without the user having to reauthenticate.


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:
Copy link
Collaborator

Choose a reason for hiding this comment

The 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
Copy link
Collaborator

Choose a reason for hiding this comment

The 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
Copy link
Collaborator

Choose a reason for hiding this comment

The 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. 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).


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:
Copy link
Collaborator

Choose a reason for hiding this comment

The 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The 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?


Copy link
Collaborator

Choose a reason for hiding this comment

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

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.

## 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}}
Copy link
Collaborator

Choose a reason for hiding this comment

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

For this to work you'll need a spec-urls front matter key with a value of https://w3c.github.io/secure-payment-confirmation.


## 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/)
Binary file added files/en-us/web/api/spc/spc-dialog.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.