Integration of Secure Payment Confirmation

files/en-us/web/api/payment_request_api/Using_secure_payment_confirmation/index.md

@@ -0,0 +1,175 @@
+---
+title: Using Secure Payment Confirmation
+slug: Web/API/Payment_Request_API/Using_secure_payment_confirmation
+page-type: guide
+spec-urls:
+  - https://w3c.github.io/payment-request/
+  - https://w3c.github.io/payment-method-id/
+  - https://w3c.github.io/webauthn/
+---
+
+{{securecontext_header}}{{DefaultAPISidebar("Payment Request API")}}
+
+Secure Payment Confirmation (SPC), available through the Payment Request 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).
+
+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.
+
+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 M118 transaction dialog for SPC:
+
+![Chrome M118 transaction dialog for SPC](chrome-tx-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.
+
+## Payment request method
+
+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"`](/en-US/docs/Web/API/Payment_Request_API/Concepts#secure-payment-confirmation).
+
+## Web authentication extension
+
+Secure Payment Confirmation defines a [Web Authentication extension](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions), [`payment`](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions#payment), which adds three payments-specific capabilities on top of traditional Web Authentication:
+
+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.
+
+## Examples
+
+### Creating a credential
+
+Creating a credential in Secure Payment Confirmation is done by the same {{domxref("CredentialsContainer.create()", "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: {
+    // Assuming that userId is ASCII-only
+    id: Uint8Array.from(userId, (c) => c.charCodeAt(0)),
+    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`).
+
+In this 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`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/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
+
+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
+
+{{Specifications}}
+
+## See also
+
+- [Payment Request API](/en-US/docs/Web/API/Payment_Request_API)
+- [Payment Method Identifiers](/en-US/docs/Web/API/Payment_Request_API/Concepts#payment_method_identifiers)
+- [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/)

files/en-us/web/api/payment_request_api/concepts/index.md

@@ -34,10 +34,14 @@ Payment handlers are identified by **payment method identifiers**, which are str
 
 ### Standardized payment method identifiers
 
-There is currently only one registered [standardized payment method identifier](https://www.w3.org/TR/payment-method-id/#registry) (more may be added in the future):
+Standardized payment method identifiers are those listed in the [payment method registry](https://www.w3.org/TR/payment-method-id/#registry).
+
+- `secure-payment-confirmation`
+
+  - : Identifies the [Secure Payment Confirmation](https://w3c.github.io/secure-payment-confirmation) method. The payment request data for this method is defined by the {{domxref("SecurePaymentConfirmationRequest")}} dictionary. For more information see [Using Secure Payment Confirmation](/en-US/docs/Web/API/Payment_Request_API/Using_secure_payment_confirmation).
 
 - `basic-card`
-  - : Payments are handled by the Basic Card Payment specification. See {{domxref("BasicCardRequest")}} for details. **_Should have an article about this specification and how to use it_.**
+  - : This payment method identifier was intended to facilitate card-based payments on the Web through the Payment Request API. **The [Web Payments Working Group](https://www.w3.org/groups/wg/payments) has deprecated this payment method.**
 
 ### URL-based payment method identifiers
 

files/en-us/web/api/paymentrequest/paymentrequest/index.md

@@ -28,17 +28,14 @@ new PaymentRequest(methodData, details, options)
     contains the following fields:
 
     - `supportedMethods`
-      - : For early implementations of the spec, this was a sequence of identifiers for
-        payment methods that the merchant website accepts. Starting with more recent
-        browsers, this parameter is more generic than credit cards, it is a single
-        string, and the meaning of the `data` parameter
-        changes with the `supportedMethods`. For example, the Example Pay payment method
-        is selected by specifying the string `https://example.com/pay` here.
+
+      - : A string containing a [payment method identifier](en-US/docs/Web/API/Payment_Request_API/Concepts#payment_method_identifiers). This is either a URL or one of the the [standardized payment method identifiers](en-US/docs/Web/API/Payment_Request_API/Concepts#standardized_payment_method_identifiers). The value and structure of the `data` field will vary depending on the value of the `supportedMethods` field.
+
     - `data`
       - : A JSON-serializable object that provides optional information that might be
         needed by the supported payment methods. This has to conform to the type expected
         by the payment handler indicated by `supportedMethods`. Developers need to consult
-        whomever controls the payment methods for the expected shape of the data object.
+        whomever controls the payment methods for the expected shape of the data object. If `supportedMethods` is `secure-payment-confirmation`, then the data needs to confirm to the [SecurePaymentConfirmationRequest dictionary](/en-US/docs/Web/API/SecurePaymentConfirmationRequest).
 
 - `details`
 

files/en-us/web/api/securepaymentconfirmationrequest/index.md

@@ -0,0 +1,40 @@
+---
+title: SecurePaymentConfirmationRequest
+slug: Web/API/SecurePaymentConfirmationRequest
+page-type: web-api-interface
+spec-urls: https://w3c.github.io/secure-payment-confirmation/#sctn-securepaymentconfirmationrequest-dictionary
+---
+
+{APIRef("Payment Request API")}}
+
+The **`SecurePaymentConfirmationRequest`** dictionary describes input to the [Payment Request API](/en-US/docs/Web/API/Payment_Request_API) when used to authenticate a user during an e-commerce transaction [using SPC with Payment Request API](/en-US/docs/Web/API/Payment_Request_API/Using_secure_payment_confirmation).
+
+An instance of this dictionary must be passed into the {{domxref("PaymentRequest.PaymentRequest()", "PaymentRequest()")}} constructor as the value of the [`data`](/en-US/docs/Web/API/PaymentRequest/PaymentRequest#data) field corresponding to a [`supportedMethods`](https://developer.mozilla.org/en-US/docs/Web/API/PaymentRequest/PaymentRequest#supportedmethods) value of `"secure-payment-confirmation"`.
+
+## Instance properties
+
+- `challenge`
+  - : A random [challenge](/en-US/docs/Web/API/CredentialsContainer/create#challenge) that the relying party generates on the server side to prevent replay attacks.
+- `rpId`
+  - : The [Relying Party Identifier](/en-US/docs/Web/API/CredentialsContainer/get#rpid) of the credentials.
+- `credentialIds`
+  - : The list of credential identifiers for the given instrument.
+- `instrument`
+  - : The description of the instrument name and icon to display during registration and to be signed along with the transaction details.
+- `timeout`
+  - : The number of milliseconds before the request to sign the transaction details times out. At most 1 hour.
+- `payeeName` {{optional_inline}}
+  - : The display name of the payee that this SPC call is for (e.g., the merchant). Optional, may be provided alongside or instead of `payeeOrigin`.
+- `payeeOrigin`
+  - : The origin of the payee that this SPC call is for (e.g., the merchant). Optional, may be provided alongside or instead of `payeeName`.
+- `extensions`
+  - : Any [WebAuthn extensions](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions) that should be used for the passed credential(s). The caller does not need to specify the [`payment` extension](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions#payment); this is added automatically.
+- `locale`
+  - : An optional list of well-formed {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}} language tags, in descending order of priority, that identify the local preferences of the website. That is, this represents a language priority list {{RFC(4647, "Matching of Language Tags")}}, which the user agent can use to perform [language negotiation](/en-US/docs/Web/HTTP/Content_negotiation) and locale-affected formatting with the caller.
+    > **Note:** The locale is distinct from language or direction metadata associated with specific input members, in that it represents the caller's requested localized experience rather than assertion about a specific string value. See [SPC internationalization Considerations](https://w3c.github.io/secure-payment-confirmation/#sctn-i18n-considerations) for more discussion.
+- `showOptOut`
+  - : Whether the user should be given a chance to opt-out during the [transaction confirmation UX](https://w3c.github.io/secure-payment-confirmation/#sctn-transaction-confirmation-ux). Optional, default false.
+
+## Specifications
+
+{{Specifications}}

files/en-us/web/api/web_authentication_api/webauthn_extensions/index.md

@@ -342,6 +342,37 @@ If the relying party is authorized to receive the `minPinLength` value (if its `
 
 If the relying party is not authorized, the extension is ignored, and no `"minPinLength"` output value is provided.
 
+### `payment`
+
+- Usable in: Registration ({{domxref("CredentialsContainer.create()","create()")}})
+- Processed by: User agent
+- Specification: [Secure Payment Confirmation](https://w3c.github.io/secure-payment-confirmation/)
+
+Allows a relying party to request the creation of a WebAuthn credential that may be used – by both the Relying Party and other parties – with Secure Payment Confirmation; see [Using Secure Payment Confirmation](/en-US/docs/Web/API/Payment_Request_API/Using_secure_payment_confirmation).
+
+#### Input
+
+The inputs for the `payment` extension are defined in the [AuthenticationExtensionsPaymentInputs dictionary](https://w3c.github.io/secure-payment-confirmation/#dictdef-authenticationextensionspaymentinputs)
+
+- `isPayment`
+  - : A boolean that indicates that the extension is active.
+- `rpID`
+  - : The [Relying Party](https://w3c.github.io/webauthn/#relying-party) id of the credential(s) being used. Only used at authentication time; not registration.
+- `topOrigin`
+  - : The origin of the top-level frame. Only used at authentication time; not registration.
+- `payeeName`
+  - : The payee name, if present, that was displayed to the user. Only used at authentication time; not registration.
+- `payeeOrigin`
+  - : The payee origin, if present, that was displayed to the user. Only used at authentication time; not registration.
+- `total`
+  - : The transaction amount that was displayed to the user. Only used at authentication time; not registration. The total is of type [PaymentCurrencyAmount](https://w3c.github.io/payment-request/#dom-paymentcurrencyamount).
+- `instrument`
+  - : The instrument details that were displayed to the user. Only used at authentication time; not registration. The instrument is of type [PaymentCredentialInstrument](https://w3c.github.io/secure-payment-confirmation/#dictdef-paymentcredentialinstrument).
+
+#### Output
+
+None
+
 ## Specifications
 
 There are a number of places that WebAuthn extensions are specified. IANA's [WebAuthn Extension Identifiers](https://www.iana.org/assignments/webauthn/webauthn.xhtml#webauthn-extension-ids) provides a registry of all extensions, but bear in mind that some may be deprecated.