diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
new file mode 100644
index 00000000..ca722e8a
--- /dev/null
+++ b/.github/CODEOWNERS
@@ -0,0 +1,2 @@
+/.github/ @marcoscaceres
+index.html @marcoscaceres @ianbjacobs @stephenmcgruer @rsolomakhin
diff --git a/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md
similarity index 100%
rename from CODE_OF_CONDUCT.md
rename to .github/CODE_OF_CONDUCT.md
diff --git a/CONTRIBUTING.md b/.github/CONTRIBUTING.md
similarity index 100%
rename from CONTRIBUTING.md
rename to .github/CONTRIBUTING.md
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 9ca265d1..60a0e8e9 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -2,16 +2,12 @@ closes #???
The following tasks have been completed:
- * [ ] Confirmed there are no ReSpec errors/warnings.
* [ ] Modified Web platform tests (link)
- * [ ] Modified MDN Docs (link)
- * [ ] Has undergone security/privacy review (link)
Implementation commitment:
- * [ ] Safari (link to issue)
- * [ ] Chrome (link to issue)
- * [ ] Firefox (link to issue)
- * [ ] Edge (public signal)
+ * [ ] WebKit (link to issue)
+ * [ ] Chromium (link to issue)
+ * [ ] Gecko (link to issue)
Optional, impact on Payment Handler spec?
diff --git a/.github/workflows/auto-publish.yml b/.github/workflows/auto-publish.yml
new file mode 100644
index 00000000..16e582a3
--- /dev/null
+++ b/.github/workflows/auto-publish.yml
@@ -0,0 +1,23 @@
+# See https://w3c.github.io/spec-prod/
+name: Node CI
+
+on:
+ push:
+ branches:
+ - gh-pages
+ pull_request: {}
+
+jobs:
+ validate-and-publish:
+ name: Validate and Publish
+ runs-on: ubuntu-latest # only linux supported at present
+ steps:
+ - uses: actions/checkout@v4
+ - uses: w3c/spec-prod@v2
+ with:
+ TOOLCHAIN: respec
+ W3C_ECHIDNA_TOKEN: ${{ secrets.ECHIDNA_TOKEN }}
+ W3C_WG_DECISION_URL: "https://www.w3.org/2016/04/14-wpwg-minutes.html#item02"
+ W3C_NOTIFICATIONS_CC: "${{ secrets.CC }}"
+ W3C_BUILD_OVERRIDE: |
+ specStatus: CRD
diff --git a/.github/workflows/tidy.yml b/.github/workflows/tidy.yml
new file mode 100644
index 00000000..42755566
--- /dev/null
+++ b/.github/workflows/tidy.yml
@@ -0,0 +1,20 @@
+name: Tidy document
+on:
+ workflow_dispatch: {}
+ push:
+ branches:
+ - gh-pages
+
+jobs:
+ tidy:
+ name: Tidy up
+ runs-on: macos-latest
+ steps:
+ - uses: actions/checkout@v2
+ - run: brew install tidy-html5
+ - run: tidy -config tidyconfig.txt -o index.html index.html
+ - uses: peter-evans/create-pull-request@v3
+ with:
+ title: "Tidied up document using tidy-html5"
+ commit-message: "chore(tidy): tidy up document"
+ branch: html-tidy
diff --git a/README.md b/README.md
index 36a8267d..a88e8cb9 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,5 @@
## Payment Request API
- * [Latest published version](https://www.w3.org/TR/payment-request/)
- * [Editors' draft](https://w3c.github.io/payment-request/)
+ * [Latest draft](https://www.w3.org/TR/payment-request/)
* [Web Payments Working Group](https://www.w3.org/Payments/WG/).
diff --git a/errata.html b/errata.html
new file mode 100644
index 00000000..29116fff
--- /dev/null
+++ b/errata.html
@@ -0,0 +1,50 @@
+
+
+
+
+ Payment Request API Errata
+
+
+
+
+
+ ## Abstract
+ This document catalogues errata for the [Payments Request API](https://w3.org/TR/payment-request/) W3C Recommendation.
+
+
+ ## Process for submitting errata
+
+ Please [file an issue](https://github.com/w3c/payment-request/issues) on Github.
+
+ ## Unaddressed errata
+ None.
+
+ ## Errata approved by the Working Group
+ None.
+
+
diff --git a/index.html b/index.html
index 53d8ab6a..66b16995 100644
--- a/index.html
+++ b/index.html
@@ -9,6 +9,7 @@
'remove'>
-
-
+
Payment Request API
@@ -97,13 +92,38 @@
facilitate the payment flow between merchant and user.
-
+
+
+ In September 2022 the Web Payments Working Group published a Payment
+ Request Recommendation. Following privacy and internationalization
+ reviews, the Recommendation excluded
+ capabilities related to billing and shipping addresses. However,
+ implementations have continued to support those features interoperably,
+ and so the Working Group has decided to try to re-align the
+ specification with implementations, and re-engage the community on
+ associated issues.
+
+
+ This document is a Candidate Recommendation Snapshot based on the text
+ of the original Recommendation. A subsequent Candidate Recommendation
+ Draft will add back address capabilities and a small number of other
+ changes made since publication of the Recommendation.
+
+
+ As part of adding back support for addresses, this specification now
+ refers to the address components defined in the Contact Picker API rather
+ than define those components itself. Indeed, the Contact Picker API is
+ derived from the original definitions found in Payment Request API, and
+ pulled out of the specification because addresses are useful on the Web
+ beyond payments.
+
- The working group maintains
- a list of all bug reports that the group has not yet addressed.
- Pull requests with proposed specification text for outstanding issues
- are strongly encouraged.
+ The Working Group plans to engage in discussion and follow the usual
+ review process before advancing the specification to Proposed
+ Recommendation status.
The working group will demonstrate implementation experience by
@@ -114,57 +134,6 @@
"https://wpt.live/payment-request/">test suite (i.e., each test
corresponds to a MUST requirement of the specification).
-
- There has been no change in dependencies on other workings groups
- during the development of this specification.
-
-
-
- Changes since last publication
-
-
- Substantive changes to the Payment Request API since the 9 July 2018
- version are as follows. The complete list of changes, including all
- editorial changes, is viewable in the commit
- history.
-
-
-
Added support for notification when the user selects a payment
- handler, but before confirming payment. This allows merchant to
- update totals, validate acceptance, etc.
-
-
Added support to notify site of billing address selection. This
- allows a merchant to update a total (e.g., for VAT in Europe). To
- enhance privacy, only some billing address data is returned to the
- merchant as long as the user has not confirmed payment.
-
-
Added support for {{retry()}} and
- fine-grain error reporting to the user.
-
-
Added support for merchant validation by the payment handler.
-
-
Clearer definition of
- canMakePayment() and worked to align implementations.
- canMakePayment() does not reveal whether payment handler is
- primed to pay.
-
-
Removed `languageCode` and `regionCode` from {{PaymentAddress}}.
-
-
Removed `currencySystem`.
-
-
"Payment request is showing" boolean now attached to
- top-level browsing context. Previously, only a single payment UI was
- allowed to be shown at a time across the whole browser. This now
- allows multiple browser tabs to show a payment UI at the same time
- (for those payment handlers able to support it).
-
-
Integrated with [[[feature-policy]]].
-
-
Defined handling of multiple applicable modifiers.
-
-
-
@@ -183,15 +152,42 @@
and who authenticates and authorizes payment as required.
The payment method: the means that the payer uses to pay
- the payee (e.g., a basic card payment). The payment method
- provider establishes the ecosystem to support that payment
+ the payee (e.g., a card payment or credit transfer). The payment
+ method provider establishes the ecosystem to support that payment
method.
+
+ A payment method defines:
+
+
+
+ An optional additional data
+ type
+
+
+ Optionally, an IDL type that the payment method expects to
+ receive as the {{PaymentMethodData}}'s {{PaymentMethodData/data}}
+ member. If not specified for a given payment method, no conversion to
+ IDL is done and the payment method will receive
+ {{PaymentMethodData/data}} as JSON.
+
+
+ Steps to validate payment method data
+
+
+ Algorithmic steps that specify how a payment method validates
+ the {{PaymentMethodData/data}} member of the {{PaymentMethodData}},
+ after it is converted to the payment method's [=Payment
+ Method/additional data type=]. If not specified for a given payment
+ method, no validation is done.
+
+
The details of how to fulfill a payment request for a given payment
- method is an implementation detail of a payment handler.
- Concretely, each payment handler defines:
+ method is an implementation detail of a payment
+ handler, which is an application or service that handles requests
+ for payment. Concretely, a payment handler defines:
@@ -200,9 +196,7 @@
How a payment handler determines whether it, or the user, can
potentially "make a payment" is also an implementation detail of a
- payment handler. For an example, see the can
- make payment algorithm of [[[?payment-method-basic-card]]].
+ payment handler.
Steps to respond to a payment request:
@@ -210,9 +204,7 @@
Steps that return an object or dictionary that a merchant uses
to process or validate the transaction. The structure of this object
- is specific to each payment method. For an example of such an
- object, see the {{BasicCardResponse}} dictionary of
- [[[?payment-method-basic-card]]].
+ is specific to each payment method.
Steps for when a user changes payment method (optional)
@@ -287,18 +279,17 @@
"modifiers" to how payments are made. For example, "if you pay with a
card belonging to network X, it incurs a US$3.00 processing fee".
-
The |options|: Optionally, a list of things as
- PaymentOptions that the site needs to deliver the good or
- service (e.g., for physical goods, the merchant will typically need a
- physical address to ship to. For digital goods, an email will usually
- suffice).
+
The |options|: Optionally, a list of things as {{PaymentOptions}}
+ that the site needs to deliver the good or service (e.g., for physical
+ goods, the merchant will typically need a physical address to ship to.
+ For digital goods, an email will usually suffice).
-
+
Once a {{PaymentRequest}} is constructed, it's presented to the end
- user via the show() method. The show() returns a promise
- that, once the user confirms request for payment, results in a
- PaymentResponse.
+ user via the {{PaymentRequest/show()}} method. The
+ {{PaymentRequest/show()}} returns a promise that, once the user
+ confirms request for payment, results in a {{PaymentResponse}}.
information in order for a merchant to fulfill a purchase (e.g., the
user's shipping address, in case a physical good needs to be
shipped). To request this information, a merchant can pass a third
- optional argument (|options|) to the {{PaymentRequest}} constructor
- indicating what information they require. When the payment request is
- shown, the user agent will request this information from the end user
- and return it to the merchant when the user accepts the payment
- request.
+ optional argument (|options:PaymentOptions |) to the
+ {{PaymentRequest}} constructor indicating what information they
+ require. When the payment request is shown, the user agent will
+ request this information from the end user and return it to the
+ merchant when the user accepts the payment request.
const options = {
@@ -521,13 +513,14 @@
};
async function checkShipping(request) {
try {
- const json = request.shippingAddress.toJSON();
+ const { shippingAddress } = request;
- await ensureCanShipTo(json);
- const { shippingOptions, total } = await calculateShipping(json);
+ await ensureCanShipTo(shippingAddress);
+ const { shippingOptions, total } = await calculateShipping(shippingAddress);
return { shippingOptions, total };
} catch (err) {
+ // Shows error to user in the payment sheet.
return { error: `Sorry! we can't ship to your address.` };
}
}
@@ -538,15 +531,14 @@
Fine-grained error reporting
- A developer can use the shippingAddressErrors member of the
- PaymentDetailsUpdate dictionary to indicate that there are
- validation errors with specific attributes of a {{PaymentAddress}}.
- The shippingAddressErrors
- member is a AddressErrors dictionary, whose members
- specifically demarcate the fields of a physical address that
- are erroneous while also providing helpful error messages to be
- displayed to the end user.
+ A developer can use the
+ {{PaymentDetailsUpdate/shippingAddressErrors}} member of the
+ {{PaymentDetailsUpdate}} dictionary to indicate that there are
+ validation errors with specific attributes of a {{ContactAddress}}.
+ The {{PaymentDetailsUpdate/shippingAddressErrors}} member is a
+ {{AddressErrors}} dictionary, whose members specifically demarcate
+ the fields of a [=physical address=] that are erroneous while also
+ providing helpful error messages to be displayed to the end user.
request.onshippingaddresschange = ev => {
@@ -565,21 +557,21 @@
}
-
+
POSTing payment response back to a server
- It's expected that data in a PaymentResponse will be POSTed
- back to a server for processing. To make this as easy as possible,
- PaymentResponse can use the [=default toJSON steps=] (i.e.,
+ It's expected that data in a {{PaymentResponse}} will be POSTed back
+ to a server for processing. To make this as easy as possible,
+ {{PaymentResponse}} can use the [=default toJSON steps=] (i.e.,
`.toJSON()`) to serializes the object directly into JSON. This makes
it trivial to POST the resulting JSON back to a server using the
[[[fetch]]]:
async function doPaymentRequest() {
- const payRequest = new PaymentRequest(methodData, details, options);
+ const payRequest = new PaymentRequest(methodData, details);
const payResponse = await payRequest.show();
let result = "";
try {
@@ -598,8 +590,31 @@
doPaymentRequest();
+
+
+ Using with cross-origin iframes
+
+
+ To indicate that a cross-origin [^iframe^] is allowed to invoke the
+ payment request API, the [^iframe/allow^] attribute along with the
+ "payment" keyword can be specified on the [^iframe^] element.
+
+ If the [^iframe^] will be navigated across multiple origins that
+ support the Payment Request API, then one can set [^iframe/allow^] to
+ `"payment *"`. The [[[permissions-policy]]] specification provides
+ further details and examples.
+
+ The {{PaymentRequest/shippingAddress}},
+ {{PaymentRequest/shippingOption}}, and
+ {{PaymentRequest/shippingType}} attributes are populated during
+ processing if the {{PaymentOptions/requestShipping}} member is set.
A |request|'s payment-relevant browsing context is that
- {{PaymentRequest}}'s relevant global object's browsing context's
+ {{PaymentRequest}}'s [=relevant global object=]'s browsing context's
top-level browsing context. Every payment-relevant browsing
context has a payment request is showing boolean, which
prevents showing more than one payment UI at a time.
@@ -671,20 +684,20 @@
+ "payment-request-constructor.https.sub.html, payment-request-insecure.http.html">
The PaymentRequest(|methodData|,
|details|, |options|) constructor MUST act as follows:
-
-
If the current settings object's [=environment settings
- object / responsible document=] is not allowed to use the
- "[=payment-feature|payment=]" feature, then [=exception/throw=] a
- {{"SecurityError"}} {{DOMException}}.
+
+
If [=this=]'s [=relevant global object=]'s [=associated
+ `Document`=] is not allowed to use the "payment"
+ permission, then [=exception/throw=] a {{"SecurityError"}}
+ {{DOMException}}.
Establish the request's id:
@@ -699,7 +712,7 @@
Let |serializedMethodData| be an empty list.
Process payment methods:
-
+
If the length of the |methodData| sequence is zero, then
[=exception/throw=] a {{TypeError}}, optionally informing the
developer that at least one payment method is required.
@@ -709,8 +722,8 @@
For each |paymentMethod| of |methodData|:
Run the steps
- to validate a payment method identifier with
+ "payment-request-ctor-pmi-handling.https.sub.html">Run the
+ steps to validate a payment method identifier with
|paymentMethod|.{{PaymentMethodData/supportedMethods}}. If it
returns false, then throw a {{RangeError}} exception.
Optionally, inform the developer that the payment method
@@ -726,21 +739,23 @@
If |seenPMIs| [=set/contain|contains=] |pmi| throw a
- {{RangeError}} {{DOMException}} optionally letting the
- developer this [=payment method identifier=] is a duplicate.
+ {{RangeError}} {{DOMException}} optionally informing the
+ developer that this [=payment method identifier=] is a
+ duplicate.
[=set/Append=] |pmi| to |seenPMIs|.
If the {{PaymentMethodData/data}} member of
|paymentMethod| is missing, let |serializedData| be null.
- Otherwise, let |serializedData| be the result of
- JSON-serializing
- |paymentMethod|.{{PaymentMethodData/data}} into a string.
- Rethrow any exceptions.
+ Otherwise, let |serializedData| be the result of [=serialize
+ a JavaScript value to a JSON string|serialize=]
+ |paymentMethod|.{{PaymentMethodData/data}} into a JSON
+ string. Rethrow any exceptions.
-
If |serializedData| is not null, and if required by the
- specification that defines the
- |paymentMethod|.supportedMethods:
+
If |serializedData| is not null, and if the specification
+ that defines the
+ |paymentMethod|.{{PaymentMethodData/supportedMethods}}
+ specifies an [=Payment Method/additional data type=]:
Let |object| be the result of JSON-parsing
@@ -748,17 +763,22 @@
- [=converted to an IDL value|Convert=] |object| to an
- IDL value of the type specified by the specification
- that defines the
- |paymentMethod|.supportedMethods (e.g.,
- {{BasicCardRequest}} in the case of
- [[[?payment-method-basic-card]]]). Rethrow any
+ Let |idl| be the result of [=converted to an IDL
+ value|converting=] |object| to an IDL value of the
+ [=Payment Method/additional data type=]. Rethrow any
exceptions.
+
+
+
+ Run the steps to validate payment method data,
+ if any, from the specification that defines the
+ |paymentMethod|.{{PaymentMethodData/supportedMethods}}
+ on |object|. Rethrow any exceptions.
+
- This step assures that any IDL type conversion errors
- are caught as early as possible.
+ These step assures that any IDL type conversion and
+ validation errors are caught as early as possible.
@@ -774,18 +794,19 @@
Process the total:
+ "payment-request-ctor-currency-code-checks.https.sub.html">
Check and canonicalize total amount
|details|.{{PaymentDetailsInit/total}}.{{PaymentItem/amount}}.
Rethrow any exceptions.
-
If the displayItems member of |details| is present, then
- for each |item| in |details|.displayItems:
+
If the {{PaymentDetailsBase/displayItems}} member of |details| is
+ present, then for each |item| in
+ |details|.{{PaymentDetailsBase/displayItems}}:
+ "payment-request-ctor-currency-code-checks.https.sub.html">
Check and canonicalize amount
|item|.{{PaymentItem/amount}}. Rethrow any exceptions.
@@ -797,29 +818,32 @@
present and set to true, process shipping options:
For each |option:PaymentShippingOption| in
+ |details|.{{PaymentDetailsBase/shippingOptions}}:
+ "payment-request-ctor-currency-code-checks.https.sub.html">
Check and canonicalize amount
|item|.{{PaymentItem/amount}}. Rethrow any exceptions.
-
If |seenIDs| contains |option|.id, then throw
- a {{TypeError}}. Optionally, inform the developer that
+
If |seenIDs| contains
+ |option|.{{PaymentShippingOption/id}}, then throw a
+ {{TypeError}}. Optionally, inform the developer that
shipping option IDs must be unique.
Set |modifiers| to
+ |details|.{{PaymentDetailsBase/modifiers}}.
For each |modifier| of |modifiers|:
@@ -848,7 +873,7 @@
|modifier| is present, then:
+ "payment-request-ctor-currency-code-checks.https.sub.html">
Check and canonicalize total amount
|modifier|.{{PaymentDetailsModifier/total}}.{{PaymentItem/amount}}.
Rethrow any exceptions.
@@ -861,7 +886,7 @@
+ "payment-request-ctor-currency-code-checks.https.sub.html">
Check and canonicalize amount
|item|.{{PaymentItem/amount}}. Rethrow any
exceptions.
@@ -871,9 +896,10 @@
If the {{PaymentDetailsModifier/data}} member of
|modifier| is missing, let |serializedData| be null.
Otherwise, let |serializedData| be the result of
- JSON-serializing
- |modifier|.{{PaymentDetailsModifier/data}} into a string.
- Rethrow any exceptions.
+ [=serialize a JavaScript value to a JSON
+ string|serialize=]
+ |modifier|.{{PaymentDetailsModifier/data}} into a JSON
+ string. Rethrow any exceptions.
Add the tuple
(|modifier|.{{PaymentDetailsModifier/supportedMethods}},
@@ -893,21 +919,21 @@
Let |request:PaymentRequest| be a new {{PaymentRequest}}.
-
Set |request|.[=PaymentRequest/[[handler]]=] to `null`.
+
Set |request|.{{PaymentRequest/[[handler]]}} to `null`.
-
Set |request|.[=PaymentRequest/[[options]]=] to |options|.
+
Set |request|.{{PaymentRequest/[[options]]}} to |options|.
Set |request|.{{PaymentRequest/[[state]]}} to
- "[=state/created=]".
+ "[=PaymentRequest/created=]".
Set |request|.{{PaymentRequest/[[updating]]}} to false.
-
Set |request|.[=PaymentRequest/[[details]]=] to |details|.
+
Set |request|.{{PaymentRequest/[[details]]}} to |details|.
-
Set |request|.[=PaymentRequest/[[serializedModifierData]]=] to
+
Set |request|.{{PaymentRequest/[[serializedModifierData]]}} to
|serializedModifierData|.
-
Set |request|.[=PaymentRequest/[[serializedMethodData]]=] to
+
Set |request|.{{PaymentRequest/[[serializedMethodData]]}} to
|serializedMethodData|.
Set |request|.{{PaymentRequest/[[response]]}} to null.
@@ -927,14 +953,14 @@
-
+
id attribute
- When getting, the id attribute returns this
+ When getting, the {{PaymentRequest/id}} attribute returns this
{{PaymentRequest}}'s
- [=PaymentRequest/[[details]]=].{{PaymentDetailsInit/id}}.
+ {{PaymentRequest/[[details]]}}.{{PaymentDetailsInit/id}}.
@@ -944,26 +970,27 @@
-
+
show() method
- The show() method is called when a developer wants to begin
- user interaction for the payment request. The show() method
- returns a {{Promise}} that will be resolved when the user
- accepts the payment request. Some kind of user interface will
- be presented to the user to facilitate the payment request after
- the show() method returns.
+ The {{PaymentRequest/show()}} method is called when a developer
+ wants to begin user interaction for the payment request. The
+ {{PaymentRequest/show()}} method returns a {{Promise}} that will be
+ resolved when the user accepts the payment request. Some
+ kind of user interface will be presented to the user to facilitate
+ the payment request after the {{PaymentRequest/show()}} method
+ returns.
Each payment handler controls what happens when multiple browsing
- context simultaneously call the show() method. For instance,
- some payment handlers will allow multiple payment UIs to be shown
- in different browser tabs/windows. Other payment handlers might
- only allow a single payment UI to be shown for the entire user
- agent.
+ context simultaneously call the {{PaymentRequest/show()}} method.
+ For instance, some payment handlers will allow multiple payment UIs
+ to be shown in different browser tabs/windows. Other payment
+ handlers might only allow a single payment UI to be shown for the
+ entire user agent.
@@ -971,40 +998,67 @@
follows:
+
Let |request:PaymentRequest| be [=this=].
+
- If the [=relevant global object=] of [=this=] does not have
- [=transient activation=], return [=a promise rejected with=] with a
- {{"SecurityError"}} {{DOMException}}.
+ If the [=relevant global object=] of [=request=] does not have
+ [=transient activation=], the user agent MAY:
+
+
Return [=a promise rejected with=] with a {{"SecurityError"}}
+ {{DOMException}}.
+
+
+
+
+ This allows the user agent to not require user activation, for
+ example to support redirect flows where a user activation may
+ not be present upon redirect. See
+ for security
+ considerations.
+
+
+ See also
+
+ issue #1022 for discussion around providing more guidance
+ in the specification on when user agents should or should not
+ require a user activation for {{PaymentRequest/show()}}.
+
Let |document| be |request|'s [=relevant global object=]'s
+ [=associated `Document`=].
If |document| is
not [=Document/fully active=], then return a promise rejected
with an {{"AbortError"}} {{DOMException}}.
+
If |document|'s [=Document/visibility state=] is not `"visible"`,
+ then return a promise rejected with an {{"AbortError"}}
+ {{DOMException}}.
+
Optionally, if the user agent wishes to disallow the call
- to show() to protect the user, then return a promise
- rejected with a {{"SecurityError"}} {{DOMException}}. For
+ to {{PaymentRequest/show()}} to protect the user, then return a
+ promise rejected with a {{"SecurityError"}} {{DOMException}}. For
example, the user agent may limit the rate at which a page
- can call show(), as described in section .
+ can call {{PaymentRequest/show()}}, as described in section
+ .
If |request|.{{PaymentRequest/[[state]]}} is not
- "[=state/created=]" then return a promise rejected with an
- {{"InvalidStateError"}} {{DOMException}}.
+ "[=PaymentRequest/created=]" then return a promise rejected
+ with an {{"InvalidStateError"}} {{DOMException}}.
For each |paymentMethod| tuple in
- |request|.[=PaymentRequest/[[serializedMethodData]]=]:
+ |request|.{{PaymentRequest/[[serializedMethodData]]}}:
Let |identifier| be the first element in the |paymentMethod|
tuple.
@@ -1058,16 +1112,16 @@
"ECMASCRIPT#sec-json.parse">JSON-parsing the second element
in the |paymentMethod| tuple.
-
If required by the specification
- that defines the |identifier|, then [=converted to an IDL
- value|convert=] |data| to an IDL value of the type specified
- there. Otherwise, [=converted to an IDL value|convert=] to
+
If the specification that defines the |identifier| specifies
+ an [=Payment Method/additional data type=], then [=converted to
+ an IDL value|convert=] |data| to an IDL value of that type.
+ Otherwise, [=converted to an IDL value|convert=] |data| to
{{object}}.
Set |request|.{{PaymentRequest/[[state]]}} to
- "[=state/closed=]".
+ "[=PaymentRequest/closed=]".
Reject |acceptPromise| with |error|.
@@ -1081,6 +1135,11 @@
Let |registeredHandlers| be a list of registered
payment handlers for the payment method |identifier|.
+
For each |handler| in |registeredHandlers|:
@@ -1097,7 +1156,7 @@
If |handlers| is empty, then:
Set |request|.{{PaymentRequest/[[state]]}} to
- "[=state/closed=]".
+ "[=PaymentRequest/closed=]".
Reject |acceptPromise| with {{"NotSupportedError"}}
{{DOMException}}.
@@ -1110,26 +1169,27 @@
-
+
Present a user interface that will allow the user to interact
with the |handlers|. The user agent SHOULD prioritize the user's
- preference when presenting payment methods.
+ preference when presenting payment methods. The user interface
+ SHOULD be presented using the language and locale-based
+ formatting that matches the |document|'s [=document
+ element|document element's=] [=Node/language=], if any, or an
+ appropriate fallback if that is not available.
For each |tuple| in
- [=PaymentRequest/[[serializedModifierData]]=]:
+ {{PaymentRequest/[[serializedModifierData]]}}:
If the first element of |tuple| (a PMI) matches the
payment method identifier of
- |request|.[=PaymentRequest/[[handler]]=], then append the second
+ |request|.{{PaymentRequest/[[handler]]}}, then append the second
element of |tuple| (the serialized method data) to |modifiers|.
@@ -1169,34 +1229,33 @@
user agent SHOULD send the appropriate data from |request| to the
user-selected payment handler in order to guide the user
through the payment process. This includes the various attributes
- and other internal slots of |request| (some MAY be excluded for
- privacy reasons where appropriate).
+ and other [=internal slots=] of |request| (some MAY be excluded
+ for privacy reasons where appropriate).
Handling of multiple applicable modifiers in the
- [=PaymentRequest/[[serializedModifierData]]=] internal slot is
- payment handler specific and beyond the scope of this
+ {{PaymentRequest/[[serializedModifierData]]}} [=internal slot=]
+ is payment handler specific and beyond the scope of this
specification. Nevertheless, it is RECOMMENDED that payment
handlers use a "last one wins" approach with items in the
- [=PaymentRequest/[[serializedModifierData]]=] list: that is to
+ {{PaymentRequest/[[serializedModifierData]]}} list: that is to
say, an item at the end of the list always takes precedence over
any item at the beginning of the list (see example below).
@@ -1269,27 +1329,29 @@
-
+
abort() method
- The abort() method is called if a developer wishes to tell
- the user agent to abort the payment |request| and to tear
- down any user interface that might be shown. The abort() can
- only be called after the show() method has been called (see
- states) and before this instance's [[\acceptPromise]]
- has been resolved. For example, developers might choose to do this
- if the goods they are selling are only available for a limited
- amount of time. If the user does not accept the payment request
- within the allowed time period, then the request will be aborted.
+ The {{PaymentRequest/abort()}} method is called if a developer
+ wishes to tell the user agent to abort the payment |request|
+ and to tear down any user interface that might be shown. The
+ {{PaymentRequest/abort()}} can only be called after the
+ {{PaymentRequest/show()}} method has been called (see
+ [=PaymentRequest/states=]) and before this instance's
+ {{PaymentRequest/[[acceptPromise]]}} has been resolved. For
+ example, developers might choose to do this if the goods they are
+ selling are only available for a limited amount of time. If the
+ user does not accept the payment request within the allowed time
+ period, then the request will be aborted.
A user agent might not always be able to abort a request.
For example, if the user agent has delegated responsibility
- for the request to another app. In this situation, abort()
- will reject the returned {{Promise}}.
+ for the request to another app. In this situation,
+ {{PaymentRequest/abort()}} will reject the returned {{Promise}}.
If |request|.{{PaymentRequest/[[response]]}} is not null, and
- |request|.{{PaymentRequest/[[response]]}}.[[\retryPromise]] is
- not null, return a promise rejected with an
+ |request|.{{PaymentRequest/[[response]]}}.{{PaymentResponse/[[retryPromise]]}}
+ is not null, return a promise rejected with an
{{"InvalidStateError"}} {{DOMException}}.
If the value of |request|.{{PaymentRequest/[[state]]}} is not
- "[=state/interactive=]" then return a promise rejected with an
- {{"InvalidStateError"}} {{DOMException}}.
+ "[=PaymentRequest/interactive=]" then return a promise rejected
+ with an {{"InvalidStateError"}} {{DOMException}}.
Set |request|.{{PaymentRequest/[[state]]}} to
- "[=state/closed=]".
+ "[=PaymentRequest/closed=]".
Reject the promise
|request|.{{PaymentRequest/[[acceptPromise]]}} with an
@@ -1340,120 +1402,93 @@
-
+
canMakePayment() method
-
+
- The canMakePayment() method can be used by the developer to
- determine if the user agent has support for one of the
- desired payment methods. See
+ The {{PaymentRequest/canMakePayment()}} method can be used by the
+ developer to determine if the user agent has support for one
+ of the desired payment methods. See
[[[#canmakepayment-protections]]].
- A true result from canMakePayment() does not imply that the
- user has a provisioned instrument ready for payment. For that, use
- hasEnrolledInstrument() instead.
+ A true result from {{PaymentRequest/canMakePayment()}} does not
+ imply that the user has a provisioned instrument ready for payment.
- The hasEnrolledInstrument() method can be used by the
- developer to determine if the user agent has support for one
- of the desired payment methods and if a payment handler
- has an instrument ready for payment. See
- [[[#canmakepayment-protections]]].
-
- A {{PaymentRequest}}'s shippingAddress attribute is populated
- when the user provides a shipping address. It is null by default.
- When a user provides a shipping address, the shipping address
- changed algorithm runs.
+ A {{PaymentRequest}}'s {{PaymentRequest/shippingAddress}} attribute
+ is populated when the user provides a shipping address. It is null by
+ default. When a user provides a shipping address, the shipping
+ address changed algorithm runs.
-
+
shippingType attribute
- A {{PaymentRequest}}'s shippingType attribute is the type of
- shipping used to fulfill the transaction. Its value is either a
- PaymentShippingType enum value, or null if none is provided by
- the developer during [=PaymentRequest.PaymentRequest()|construction=]
- (see {{PaymentOptions}}'s {{PaymentOptions/shippingType}} member).
-
-
-
-
- onmerchantvalidation attribute
-
-
- A {{PaymentRequest}}'s onmerchantvalidation attribute is an
- {{EventHandler}} for a {{MerchantValidationEvent}} named
- "merchantvalidation".
+ A {{PaymentRequest}}'s {{PaymentRequest/shippingType}} attribute is
+ the type of shipping used to fulfill the transaction. Its value is
+ either a {{PaymentShippingType}} enum value, or null if none is
+ provided by the developer during
+ [=PaymentRequest.PaymentRequest()|construction=] (see
+ {{PaymentOptions}}'s {{PaymentOptions/shippingType}} member).
-
+
onshippingaddresschange attribute
- A {{PaymentRequest}}'s onshippingaddresschange attribute is an
- {{EventHandler}} for a {{PaymentRequestUpdateEvent}} named
- shippingaddresschange.
+ A {{PaymentRequest}}'s {{PaymentRequest/onshippingaddresschange}}
+ attribute is an {{EventHandler}} for a {{PaymentRequestUpdateEvent}}
+ named shippingaddresschange.
-
+
shippingOption attribute
- A {{PaymentRequest}}'s shippingOption attribute is populated
- when the user chooses a shipping option. It is null by default. When
- a user chooses a shipping option, the shipping option changed
- algorithm runs.
+ A {{PaymentRequest}}'s {{PaymentRequest/shippingOption}} attribute is
+ populated when the user chooses a shipping option. It is null by
+ default. When a user chooses a shipping option, the shipping
+ option changed algorithm runs.
-
+
onshippingoptionchange attribute
- A {{PaymentRequest}}'s onshippingoptionchange attribute is an
- {{EventHandler}} for a {{PaymentRequestUpdateEvent}} named
- shippingoptionchange.
+ A {{PaymentRequest}}'s {{PaymentRequest/onshippingoptionchange}}
+ attribute is an {{EventHandler}} for a {{PaymentRequestUpdateEvent}}
+ named shippingoptionchange.
+ A {{PaymentRequest}}'s {{PaymentRequest/onpaymentmethodchange}}
+ attribute is an {{EventHandler}} for a {{PaymentMethodChangeEvent}}
+ named "paymentmethodchange".
@@ -1461,10 +1496,10 @@
Internal Slots
- Instances of {{PaymentRequest}} are created with the internal slots
- in the following table:
+ Instances of {{PaymentRequest}} are created with the [=internal
+ slots=] in the following table:
The methodData supplied to the constructor, but
@@ -1493,7 +1527,7 @@
A list containing the serialized string form of each
{{PaymentDetailsModifier/data}} member for each corresponding
item in the sequence
- [=PaymentRequest/[[details]]=].{{PaymentDetailsBase/modifier}},
+ {{PaymentRequest/[[details]]}}.{{PaymentDetailsBase/modifier}},
or null if no such member was present.
@@ -1503,14 +1537,14 @@
"PaymentRequest">[[\details]]
- The current PaymentDetailsBase for the payment request
+ The current {{PaymentDetailsBase}} for the payment request
initially supplied to the constructor and then updated with calls
to {{PaymentRequestUpdateEvent/updateWith()}}. Note that all
{{PaymentDetailsModifier/data}} members of
{{PaymentDetailsModifier}} instances contained in the
{{PaymentDetailsBase/modifiers}} member will be removed, as they
are instead stored in serialized form in the
- [=PaymentRequest/[[serializedModifierData]]=] internal slot.
+ {{PaymentRequest/[[serializedModifierData]]}} [=internal slot=].
@@ -1519,7 +1553,7 @@
"PaymentRequest">[[\options]]
- The PaymentOptions supplied to the constructor.
+ The {{PaymentOptions}} supplied to the constructor.
@@ -1528,46 +1562,48 @@
- The current state of the payment request, which
- transitions from:
+ The current state of the payment request, which transitions from:
- "created"
+ "created"
The payment request is constructed and has not been presented
to the user.
- "interactive"
+ "interactive"
The payment request is being presented to the user.
- "closed"
+ "closed"
The payment request completed.
- The state transitions are illustrated in the figure
- below:
+ The [=PaymentRequest/state=] transitions are illustrated in the
+ figure below:
-
- The constructor sets the initial state to
- "[=state/created=]". The show() method changes the
- state to "[=state/interactive=]". From there, the
- abort() method or any other error can send the
- state to "[=state/closed=]"; similarly, the user
- accepts the payment request algorithm and user aborts
- the payment request algorithm will change the
- state to "[=state/closed=]".
+
+ The constructor sets the initial [=PaymentRequest/state=] to
+ "[=PaymentRequest/created=]". The {{PaymentRequest/show()}}
+ method changes the [=PaymentRequest/state=] to
+ "[=PaymentRequest/interactive=]". From there, the
+ {{PaymentRequest/abort()}} method or any other error can send
+ the [=PaymentRequest/state=] to "[=PaymentRequest/closed=]";
+ similarly, the user accepts the payment request
+ algorithm and user aborts the payment request
+ algorithm will change the [=PaymentRequest/state=] to
+ "[=PaymentRequest/closed=]".
@@ -1596,7 +1632,7 @@
[[\response]]
- Null, or the PaymentResponse instantiated by this
+ Null, or the {{PaymentResponse}} instantiated by this
{{PaymentRequest}}.
@@ -1612,8 +1648,7 @@
-
+
PaymentMethodData dictionary
@@ -1641,8 +1676,8 @@
An object that provides optional information that might be needed by
- the supported payment methods. If supplied, it will be
- JSON-serialized.
+ the supported payment methods. If supplied, it will be [=serialize a
+ JavaScript value to a JSON string|serialized=].
@@ -1651,8 +1686,7 @@
with existing content on the Web.
-
+
PaymentCurrencyAmount dictionary
@@ -1663,7 +1697,7 @@
};
- A PaymentCurrencyAmount dictionary is used to supply monetary
+ A {{PaymentCurrencyAmount}} dictionary is used to supply monetary
amounts.
@@ -1677,10 +1711,19 @@
alphabetic code (i.e., the numeric codes are not supported). Their
canonical form is upper case. However, the set of combinations of
currency code for which localized currency symbols are available is
- implementation dependent. Where a localized currency symbol is not
- available, a user agent SHOULD use U+00A4 (¤) for formatting. User
- agents MAY format the display of the currency member to
- adhere to OS conventions (e.g., for localization purposes).
+ implementation dependent.
+
+
+ When displaying a monetary value, it is RECOMMENDED that user
+ agents display the currency code, but it's OPTIONAL for user agents
+ to display a currency symbol. This is because currency symbols can
+ be ambiguous due to use across a number of different currencies
+ (e.g., "$" could mean any of USD, AUD, NZD, CAD, and so on.).
+
+
+ User agents MAY format the display of the
+ {{PaymentCurrencyAmount/currency}} member to adhere to OS
+ conventions (e.g., for localization purposes).
@@ -1698,10 +1741,10 @@
[[ISO4217]] list (e.g., XBT, XRP, etc.). If the provided code is
a currency that the browser knows how to display, then an
implementation will generally display the appropriate currency
- symbol in the user interface (e.g., "USD" is shown as "$", "GBP"
- is "£", and the non-standard "XBT" could be shown as "Ƀ"). When a
- code cannot be matched, the specification recommends browsers
- show a scarab "¤".
+ symbol in the user interface (e.g., "USD" is shown as U+0024
+ Dollar Sign ($), "GBP" is shown as U+00A3 Pound Sign (£), "PLN"
+ is shown as U+007A U+0142 Złoty (zł), and the non-standard "XBT"
+ could be shown as U+0243 Latin Capital Letter B with Stroke (Ƀ)).
Efforts are underway at ISO to account for digital currencies,
@@ -1725,12 +1768,12 @@
To check and canonicalize amount given a
- PaymentCurrencyAmount |amount|, run the following steps:
+ {{PaymentCurrencyAmount}} |amount|, run the following steps:
-
+
If the result of IsWellFormedCurrencyCode(|amount|.currency)
+ "ecma-402#sec-iswellformedcurrencycode">IsWellFormedCurrencyCode(|amount|.{{PaymentCurrencyAmount/currency}})
is false, then throw a {{RangeError}} exception, optionally informing
the developer that the currency is invalid.
-
If |amount|.value is not a valid decimal monetary
- value, throw a {{TypeError}}, optionally informing the developer
- that the currency is invalid.
+
If |amount|.{{PaymentCurrencyAmount/value}} is not a valid
+ decimal monetary value, throw a {{TypeError}}, optionally
+ informing the developer that the currency is invalid.
Set |amount|.{{PaymentCurrencyAmount/currency}} to the result of
+ ASCII uppercase |amount|.{{PaymentCurrencyAmount/currency}}.
To check and canonicalize total amount given a
- PaymentCurrencyAmount |amount|, run the following steps:
+ {{PaymentCurrencyAmount}} |amount:PaymentCurrencyAmount|, run the
+ following steps:
If the first code point of |amount|.value is U+002D
- (-), then throw a {{TypeError}} optionally informing the developer
- that a total's value can't be a negative number.
+
If the first code point of
+ |amount|.{{PaymentCurrencyAmount/value}} is U+002D (-), then throw a
+ {{TypeError}} optionally informing the developer that a total's value
+ can't be a negative number.
@@ -1801,8 +1846,7 @@
Payment details dictionaries
-
+
PaymentDetailsBase dictionary
@@ -1818,8 +1862,8 @@
displayItems member
- A sequence of PaymentItem dictionaries contains line items
- for the payment request that the user agent MAY display.
+ A sequence of {{PaymentItem}} dictionaries contains line items for
+ the payment request that the user agent MAY display.
-
+
PaymentDetailsInit dictionary
@@ -1888,9 +1930,9 @@
of the payment request.
- In addition to the members inherited from the
- PaymentDetailsBase dictionary, the following members are part
- of the PaymentDetailsInit dictionary:
+ In addition to the members inherited from the {{PaymentDetailsBase}}
+ dictionary, the following members are part of the
+ PaymentDetailsInit dictionary:
@@ -1899,8 +1941,9 @@
A free-form identifier for this payment request.
@@ -1908,7 +1951,7 @@
total member
- A PaymentItem containing a non-negative total amount for the
+ A {{PaymentItem}} containing a non-negative total amount for the
payment request.
-
+
PaymentDetailsUpdate dictionary
@@ -1934,13 +1976,13 @@
};
- The PaymentDetailsUpdate dictionary is used to update the
- payment request using {{PaymentRequestUpdateEvent/updateWith()}}.
+ The {{PaymentDetailsUpdate}} dictionary is used to update the payment
+ request using {{PaymentRequestUpdateEvent/updateWith()}}.
- In addition to the members inherited from the
- PaymentDetailsBase dictionary, the following members are part
- of the PaymentDetailsUpdate dictionary:
+ In addition to the members inherited from the {{PaymentDetailsBase}}
+ dictionary, the following members are part of the
+ {{PaymentDetailsUpdate}} dictionary:
@@ -1953,7 +1995,7 @@
{{PaymentRequestUpdateEvent/updateWith()}}, the
{{PaymentDetailsUpdate}} can contain a message in the
{{PaymentDetailsUpdate/error}} member that will be displayed to the
- user if the PaymentDetailsUpdate indicates that there are no
+ user if the {{PaymentDetailsUpdate}} indicates that there are no
valid {{PaymentDetailsBase/shippingOptions}} (and the
{{PaymentRequest}} was constructed with the
{{PaymentOptions/requestShipping}} option set to true).
@@ -1962,12 +2004,11 @@
total member
- A PaymentItem containing a non-negative
- {{PaymentItem/amount}}.
+ A {{PaymentItem}} containing a non-negative {{PaymentItem/amount}}.
Algorithms in this specification that accept a
- PaymentDetailsUpdate dictionary will throw if the
- total.{{PaymentItem/amount}}.{{PaymentCurrencyAmount/value}}
+ {{PaymentDetailsUpdate}} dictionary will throw if the
+ {{PaymentDetailsUpdate/total}}.{{PaymentItem/amount}}.{{PaymentCurrencyAmount/value}}
is a negative number.
@@ -1989,15 +2030,13 @@
- Payment method specific errors. See, for example,
- [[[?payment-method-basic-card]]]'s {{BasicCardErrors}}.
+ Payment method specific errors.
- A sequence of PaymentItem dictionaries provides additional
+ A sequence of {{PaymentItem}} dictionaries provides additional
display items that are appended to the
{{PaymentDetailsBase/displayItems}} member in the
- PaymentDetailsBase dictionary for the payment method
- identifiers in the supportedMethods member. This member is
- commonly used to add a discount or surcharge line item indicating the
- reason for the different total amount for the selected
- payment method that the user agent MAY display.
+ {{PaymentDetailsBase}} dictionary for the payment method
+ identifiers in the {{PaymentDetailsModifier/supportedMethods}}
+ member. This member is commonly used to add a discount or surcharge
+ line item indicating the reason for the different
+ {{PaymentDetailsModifier/total}} amount for the selected payment
+ method that the user agent MAY display.
It is the developer's responsibility to verify that the
- total amount is the sum of the
+ {{PaymentDetailsModifier/total}} amount is the sum of the
{{PaymentDetailsBase/displayItems}} and the
- additionalDisplayItems.
+ {{PaymentDetailsModifier/additionalDisplayItems}}.
@@ -2056,8 +2096,8 @@
An object that provides optional information that might be needed by
- the supported payment methods. If supplied, it will be
- JSON-serialized.
+ the supported payment methods. If supplied, it will be [=serialize a
+ JavaScript value to a JSON string|serialized=].
@@ -2077,27 +2117,28 @@
"shipping"
- This is the default and refers to the address being collected as the
- destination for shipping.
+ This is the default and refers to the [=physical address|address=]
+ being collected as the destination for [=shipping address|shipping=].
"delivery"
- This refers to the address being collected as the destination for
- delivery. This is commonly faster than shipping. For example, it
- might be used for food delivery.
+ This refers to the [=physical address|address=] being collected as
+ the destination for delivery. This is commonly faster than [=shipping
+ address|shipping=]. For example, it might be used for food delivery.
"pickup"
- This refers to the address being collected as part of a service
- pickup. For example, this could be the address for laundry pickup.
+ This refers to the [=physical address|address=] being collected as
+ part of a service pickup. For example, this could be the address for
+ laundry pickup.
-
+
PaymentOptions dictionary
@@ -2112,24 +2153,24 @@
};
- The PaymentOptions dictionary is passed to the
- {{PaymentRequest}} constructor and provides information about the
- options desired for the payment request.
+ The {{PaymentOptions}} dictionary is passed to the {{PaymentRequest}}
+ constructor and provides information about the options desired for the
+ payment request.
requestBillingAddress member
-
+
A boolean that indicates whether the user agent SHOULD collect
- and return the billing address associated with a payment
+ and return the [=billing address=] associated with a payment
method (e.g., the billing address associated with a credit card).
Typically, the user agent will return the billing address as part of
- the {{PaymentMethodChangeEvent}}'s methodDetails. A merchant
- can use this information to, for example, calculate tax in certain
- jurisdictions and update the displayed total. See below for privacy
- considerations regarding exposing user
- information.
+ the {{PaymentMethodChangeEvent}}'s
+ {{PaymentMethodChangeEvent/methodDetails}}. A merchant can use this
+ information to, for example, calculate tax in certain jurisdictions
+ and update the displayed total. See below for privacy considerations
+ regarding exposing user information.
requestPayerName member
@@ -2163,7 +2204,7 @@
A boolean that indicates whether the user agent SHOULD collect
- and return a shipping address as part of the payment request. For
+ and return a [=shipping address=] as part of the payment request. For
example, this would be set to true when physical goods need to be
shipped by the merchant to the user. This would be set to false for
the purchase of digital goods.
@@ -2172,21 +2213,22 @@
shippingType member
- A PaymentShippingType enum value. Some transactions require an
- address for delivery but the term "shipping" isn't appropriate. For
- example, "pizza delivery" not "pizza shipping" and "laundry pickup"
- not "laundry shipping". If requestShipping is set to true,
- then the shippingType member can influence the way the user
- agent presents the user interface for gathering the shipping
- address.
+ A {{PaymentShippingType}} enum value. Some transactions require an
+ [=physical address|address=] for delivery but the term "shipping"
+ isn't appropriate. For example, "pizza delivery" not "pizza shipping"
+ and "laundry pickup" not "laundry shipping". If
+ {{PaymentOptions/requestShipping}} is set to true, then the
+ {{PaymentOptions/shippingType}} member can influence the way the
+ user agent presents the user interface for gathering the
+ shipping address.
- The shippingType member only affects the user interface for
- the payment request.
+ The {{PaymentOptions/shippingType}} member only affects the user
+ interface for the payment request.
-
+
PaymentItem dictionary
@@ -2198,9 +2240,9 @@
};
- A sequence of one or more PaymentItem dictionaries is included
- in the PaymentDetailsBase dictionary to indicate what the
- payment request is for and the value asked for.
+ A sequence of one or more {{PaymentItem}} dictionaries is included in
+ the {{PaymentDetailsBase}} dictionary to indicate what the payment
+ request is for and the value asked for.
@@ -2209,952 +2251,292 @@
A human-readable description of the item. The user agent may
display this to the user.
+
amount member
- A PaymentCurrencyAmount containing the monetary amount for the
+ A {{PaymentCurrencyAmount}} containing the monetary amount for the
item.
pending member
- A boolean. When set to true it means that the amount member is
- not final. This is commonly used to show items such as shipping or
- tax amounts that depend upon selection of shipping address or
- shipping option. User agents MAY indicate pending fields in
- the user interface for the payment request.
+ A boolean. When set to true it means that the {{PaymentItem/amount}}
+ member is not final. This is commonly used to show items such as
+ shipping or tax amounts that depend upon selection of shipping
+ address or shipping option. User agents MAY indicate pending
+ fields in the user interface for the payment request.
- A physical address is composed of the following parts.
+ The {{PaymentCompleteDetails}} dictionary provides additional
+ information from the merchant website to the payment handler when the
+ payment request completes.
-
-
- Country
-
-
- The country corresponding to the address.
-
-
- Address line
-
-
- The most specific part of the address. It can include, for example, a
- street name, a house number, apartment number, a rural delivery
- route, descriptive instructions, or a post office box number.
-
+
+ The {{PaymentCompleteDetails}} dictionary contains the following
+ members:
+
+
- Region
+ data member
- The top level administrative subdivision of the country. For example,
- this can be a state, a province, an oblast, or a prefecture.
+ An object that provides optional information that might be needed by
+ the {{PaymentResponse}} associated [=payment method=]. If supplied,
+ it will be [=serialize a JavaScript value to a JSON
+ string|serialize=].
- The city/town portion of the address.
+ Indicates that processing of the payment failed. The user
+ agent MAY display UI indicating failure.
- Dependent locality
+ "success"
- The dependent locality or sublocality within a city. For example,
- neighborhoods, boroughs, districts, or UK dependent localities.
+ Indicates the payment was successfully processed. The user
+ agent MAY display UI indicating success.
- Postal code
+ "unknown"
- The postal code or ZIP code, also known as PIN code in India.
+ The developer did not indicate success or failure and the user
+ agent SHOULD NOT display UI indicating success or failure.
+ The {{PaymentShippingOption}} dictionary has members describing a
+ shipping option. Developers can provide the user with one or more
+ shipping options by calling the
+ {{PaymentRequestUpdateEvent/updateWith()}} method in response to a
+ change event.
+
+
- Sorting code
+ id member
- The sorting code as used in, for example, France.
+ A string identifier used to reference this {{PaymentShippingOption}}.
+ It MUST be unique for a given {{PaymentRequest}}.
- Organization
+ label member
- The organization, firm, company, or institution at the address.
+ A human-readable string description of the item. The user
+ agent SHOULD use this string to display the shipping option to
+ the user.
- Recipient
+ amount member
- The name of the recipient or contact person at the address.
+ A {{PaymentCurrencyAmount}} containing the monetary amount for the
+ item.
- Phone number
+ selected member
- The phone number of the recipient or contact person at the address.
+ A boolean. When true, it indicates that this is the default selected
+ {{PaymentShippingOption}} in a sequence. User agents SHOULD
+ display this option by default in the user interface.
- The members of the AddressErrors dictionary represent
- validation errors with specific parts of a physical address.
- Each dictionary member has a dual function: firstly, its presence
- denotes that a particular part of an address is suffering from a
- validation error. Secondly, the string value allows the developer to
- describe the validation error (and possibly how the end user can fix
- the error).
-
-
- Developers need to be aware that users might not have the ability to
- fix certain parts of an address. As such, they need to be mindful not
- to ask the user to fix things they might not have control over.
-
-
-
- addressLine member
-
-
- Denotes that the address line has a validation error. In the
- user agent's UI, this member corresponds to the input field that
- provided the {{PaymentAddress}}'s addressLine attribute's value.
-
-
- city member
-
-
- Denotes that the city has a validation error. In the user
- agent's UI, this member corresponds to the input field that
- provided the {{PaymentAddress}}'s city attribute's value.
-
-
- country member
-
-
- Denotes that the country has a validation error. In the user
- agent's UI, this member corresponds to the input field that
- provided the {{PaymentAddress}}'s country attribute's value.
-
-
- dependentLocality member
-
-
- Denotes that the dependent locality has a validation error.
- In the user agent's UI, this member corresponds to the input field
- that provided the {{PaymentAddress}}'s dependentLocality attribute's value.
-
-
- organization member
-
-
- Denotes that the organization has a validation error. In the
- user agent's UI, this member corresponds to the input field that
- provided the {{PaymentAddress}}'s organization attribute's value.
-
-
- phone member
-
-
- Denotes that the phone number has a validation error. In the
- user agent's UI, this member corresponds to the input field that
- provided the {{PaymentAddress}}'s phone attribute's value.
-
-
- postalCode member
-
-
- Denotes that the postal code has a validation error. In the
- user agent's UI, this member corresponds to the input field that
- provided the {{PaymentAddress}}'s postalCode attribute's value.
-
-
- recipient member
-
-
- Denotes that the recipient has a validation error. In the
- user agent's UI, this member corresponds to the input field that
- provided the {{PaymentAddress}}'s addressLine attribute's value.
-
-
- region member
-
-
- Denotes that the region has a validation error. In the user
- agent's UI, this member corresponds to the input field that
- provided the {{PaymentAddress}}'s region attribute's value.
-
-
- sortingCode member
-
-
- The sorting code has a validation error. In the user agent's
- UI, this member corresponds to the input field that provided the
- {{PaymentAddress}}'s sortingCode attribute's value.
-
-
-
-
-
- Creating a `PaymentAddress` from user-provided input
-
-
- The steps to create a `PaymentAddress` from
- user-provided input are given by the following algorithm. The
- algorithm takes a list |redactList|.
-
-
-
- The |redactList| optionally gives user agents the possibility to
- limit the amount of personal information about the recipient that
- the API shares with the merchant.
-
-
- For merchants, the resulting {{PaymentAddress}} object provides
- enough information to, for example, calculate shipping costs, but,
- in most cases, not enough information to physically locate and
- uniquely identify the recipient.
-
-
- Unfortunately, even with the |redactList|, recipient anonymity
- cannot be assured. This is because in some countries postal codes
- are so fine-grained that they can uniquely identify a recipient.
-
-
-
-
Let |details| be a newly created AddressInit dictionary.
-
-
If "addressLine" is not in |redactList|, set
- |details|["addressLine"] to the result of splitting the
- user-provided address line into a list.
-
-
-
If "country" is not in |redactList|, set
- |details|["country"] to the user-provided country as an upper
- case [[ISO3166-1]] alpha-2 code.
-
-
If "phone" is not in |redactList|, set |details|["phone"]
- to the user-provided phone number.
-
-
-
If "city" is not in |redactList|, set |details|["city"] to
- the user-provided city, or to the empty string if none was provided.
-
-
If "dependentLocality" is not in |redactList|, set |
- details|["dependentLocality"] to the user-provided dependent
- locality.
-
-
If "organization" is not in |redactList|, set
- |details|["organization"] to the user-provided recipient
- organization.
-
-
If "postalCode" is not in |redactList|, set
- |details|["postalCode"] to the user-provided postal code.
- Optionally, redact part of |details|["postalCode"].
-
-
- Postal codes in certain countries can be so specific as
- to uniquely identify an individual. This being a privacy
- concern, some user agents only return the part of a postal code
- that they deem sufficient for a merchant to calculate shipping
- costs. This varies across countries and regions, and so the
- choice to redact part, or all, of the postal code is left to
- the discretion of implementers in the interest of protecting
- users' privacy.
-
-
-
-
If "recipient" is not in |redactList|, set
- |details|["recipient"] to the user-provided recipient of the
- transaction.
-
-
-
- If "region" is not in |redactList|:
-
-
- In some countries (e.g., Belgium) it is uncommon for users to
- include a region as part of a physical address
- (even if all the regions of a country are part of [[ISO3166-2]]).
- As such, when the user agent knows that the user is inputting the
- address for a particular country, it might not provide a field
- for the user to input a region. In such cases, the user
- agent returns an empty string for both {{PaymentAddress}}'s
- region attribute - but the
- address can still serve its intended purpose (e.g., be valid for
- shipping or billing purposes).
-
-
-
Set |details|["region"] to the user-provided region.
-
-
-
-
If "sortingCode" is not in |redactList|, set
- |details|["sortingCode"] to the user-provided sorting code.
-
-
[=PaymentAddress.PaymentAddress()|Internally construct a new
- `PaymentAddress`=] with |details| and return the result.
-
- The PaymentShippingOption dictionary has members describing a
- shipping option. Developers can provide the user with one or more
- shipping options by calling the
- {{PaymentRequestUpdateEvent/updateWith()}} method in response to a
- change event.
-
-
-
- id member
-
-
- A string identifier used to reference this
- PaymentShippingOption. It MUST be unique for a given
- {{PaymentRequest}}.
-
-
- label member
-
-
- A human-readable string description of the item. The user
- agent SHOULD use this string to display the shipping option to
- the user.
-
- A boolean. When true, it indicates that this is the default selected
- PaymentShippingOption in a sequence. User agents SHOULD
- display this option by default in the user interface.
-
Set |response|.{{PaymentResponse/[[retryPromise]]}} to
+ |retryPromise|.
-
If |errorFields| was passed:
+
If |errorFields:PaymentValidationErrors| was passed:
Optionally, show a warning in the developer console if any of
the following are true:
- |request|.[=PaymentRequest/[[options]]=]["requestPayerName"] is false, and
- |errorFields|["payer"]["name"] is present.
+ |request|.{{PaymentRequest/[[options]]}}.{{PaymentOptions/requestPayerName}}
+ is false, and
+ |errorFields|.{{PaymentValidationErrors/payer}}.{{PayerErrors/name}}
+ is present.
- |request|.[=PaymentRequest/[[options]]=]["requestPayerEmail"] is false, and
- |errorFields|["payer"]["email"] is present.
+ |request|.{{PaymentRequest/[[options]]}}.{{PaymentOptions/requestPayerEmail}}
+ is false, and
+ |errorFields|.{{PaymentValidationErrors/payer}}.{{PayerErrors/email}}
+ is present.
- |request|.[=PaymentRequest/[[options]]=]["requestPayerPhone"] is false, and
- |errorFields|["payer"]["phone"] is present.
+ |request|.{{PaymentRequest/[[options]]}}.{{PaymentOptions/requestPayerPhone}}
+ is false, and
+ |errorFields|.{{PaymentValidationErrors/payer}}.{{PayerErrors/phone}}
+ is present.
- |request|.[=PaymentRequest/[[options]]=]["requestShipping"] is false, and
- |errorFields|["shippingAddress"] is present.
+ |request|.{{PaymentRequest/[[options]]}}.{{PaymentOptions/requestShipping}}
+ is false, and
+ |errorFields|.{{PaymentValidationErrors/shippingAddress}} is
+ present.
-
- If |errorFields|["paymentMethod"] member was passed, and
- if required by the specification that defines |response|'s
- payment method, then [=converted to an IDL value|convert=]
- |errorFields|'s paymentMethod member to an IDL value of
- the type specified there. Otherwise, [=converted to an IDL
+ If
+ |errorFields:PaymentValidationErrors|.{{PaymentValidationErrors/paymentMethod}}
+ member was passed, and if required by the specification that
+ defines |response|.{{PaymentResponse/methodName}}, then
+ [=converted to an IDL value|convert=] |errorFields|'s
+ {{PaymentValidationErrors/paymentMethod}} member to an IDL value
+ of the type specified there. Otherwise, [=converted to an IDL
value|convert=] to {{object}}.
By matching the
- members of |errorFields| to input fields in the user agent's UI,
- indicate to the end user that something is wrong with the data of
- the payment response. For example, a user agent might draw the
- user's attention to the erroneous |errorFields| in the browser's
- UI and display the value of each field in a manner that helps the
- user fix each error. Similarly, if the error member is
- passed, present the error in the user agent's UI. In the case
- where the value of a member is the empty string, the user agent
- MAY substitute a value with a suitable error message.
+
By matching the members of |errorFields| to input fields in
+ the user agent's UI, indicate to the end user that something is
+ wrong with the data of the payment response. For example, a user
+ agent might draw the user's attention to the erroneous
+ |errorFields| in the browser's UI and display the value of each
+ field in a manner that helps the user fix each error. Similarly,
+ if the {{PaymentValidationErrors/error}} member is passed,
+ present the error in the user agent's UI. In the case where the
+ value of a member is the empty string, the user agent MAY
+ substitute a value with a suitable error message.
@@ -3204,7 +2586,7 @@
Finally, when |retryPromise| settles, set
- |response|.[[\retryPromise]] to null.
+ |response|.{{PaymentResponse/[[retryPromise]]}} to null.
+ Represents validation errors with the {{PaymentResponse}}'s
+ {{PaymentResponse/shippingAddress}}.
error member
@@ -3249,20 +2630,30 @@
A general description of an error with the payment from which the
user can attempt to recover. For example, the user may recover by
retrying the payment. A developer can optionally pass the
- error member on its own to give a general overview of
- validation issues, or it can be passed in combination with other
- members of the PaymentValidationErrors dictionary.
+ {{PaymentValidationErrors/error}} member on its own to give a
+ general overview of validation issues, or it can be passed in
+ combination with other members of the {{PaymentValidationErrors}}
+ dictionary.
+
paymentMethod member
- A payment method specific errors. See, for example,
- [[[?payment-method-basic-card]]]'s {{BasicCardErrors}}.
+ A payment method specific errors.
-
+
PayerErrors dictionary
@@ -3274,22 +2665,22 @@
};
- The PayerErrors is used to represent validation errors with
- one or more payer details.
+ The {{PayerErrors}} is used to represent validation errors with one
+ or more payer details.
Payer details are any of the payer's name, payer's phone
number, and payer's email.
-
+
email member
Denotes that the payer's email suffers from a validation error.
In the user agent's UI, this member corresponds to the input
- field that provided the PaymentResponse's
- payerEmail attribute's value.
+ field that provided the {{PaymentResponse}}'s
+ {{PaymentResponse/payerEmail}} attribute's value.
name member
@@ -3297,8 +2688,8 @@
Denotes that the payer's name suffers from a validation error. In
the user agent's UI, this member corresponds to the input field
- that provided the PaymentResponse's payerName
- attribute's value.
+ that provided the {{PaymentResponse}}'s
+ {{PaymentResponse/payerName}} attribute's value.
phone member
@@ -3306,8 +2697,8 @@
Denotes that the payer's phone number suffers from a validation
error. In the user agent's UI, this member corresponds to the
- input field that provided the PaymentResponse's
- payerPhone attribute's value.
+ input field that provided the {{PaymentResponse}}'s
+ {{PaymentResponse/payerPhone}} attribute's value.
@@ -3334,19 +2725,18 @@
details attribute
-
+
An {{object}} or dictionary generated by a payment
method that a merchant can use to process or validate a
transaction (depending on the payment method).
@@ -3376,8 +2766,8 @@
If the {{PaymentOptions/requestShipping}} member was set to true in
- the PaymentOptions passed to the {{PaymentRequest}}
- constructor, then {{PaymentRequest/shippingOption}} will be the
+ the {{PaymentOptions}} passed to the {{PaymentRequest}} constructor,
+ then {{PaymentRequest/shippingOption}} will be the
{{PaymentShippingOption/id}} attribute of the selected shipping
option.
@@ -3388,9 +2778,9 @@
If the {{PaymentOptions/requestPayerName}} member was set to true in
- the PaymentOptions passed to the {{PaymentRequest}}
- constructor, then {{PaymentResponse/payerName}} will be the name
- provided by the user.
+ the {{PaymentOptions}} passed to the {{PaymentRequest}} constructor,
+ then {{PaymentResponse/payerName}} will be the name provided by the
+ user.
@@ -3400,9 +2790,9 @@
If the {{PaymentOptions/requestPayerEmail}} member was set to true in
- the PaymentOptions passed to the {{PaymentRequest}}
- constructor, then {{PaymentResponse/payerEmail}} will be the email
- address chosen by the user.
+ the {{PaymentOptions}} passed to the {{PaymentRequest}} constructor,
+ then {{PaymentResponse/payerEmail}} will be the email address chosen
+ by the user.
@@ -3412,9 +2802,9 @@
If the {{PaymentOptions/requestPayerPhone}} member was set to true in
- the PaymentOptions passed to the {{PaymentRequest}}
- constructor, then {{PaymentResponse/payerPhone}} will be the phone
- number chosen by the user.
+ the {{PaymentOptions}} passed to the {{PaymentRequest}} constructor,
+ then {{PaymentResponse/payerPhone}} will be the phone number chosen
+ by the user.
@@ -3426,49 +2816,88 @@
this payment response.
-
+
- complete() method
+ complete() method
- The complete() method is called after the user has accepted
- the payment request and the [[\acceptPromise]] has been
- resolved. Calling the complete() method tells the user
- agent that the payment interaction is over (and SHOULD cause any
- remaining user interface to be closed).
+ The {{PaymentResponse/complete()}} method is called after the user
+ has accepted the payment request and the
+ {{PaymentRequest/[[acceptPromise]]}} has been resolved. Calling the
+ {{PaymentResponse/complete()}} method tells the user agent
+ that the payment interaction is over (and SHOULD cause any remaining
+ user interface to be closed).
After the payment request has been accepted and the
- PaymentResponse returned to the caller, but before the caller
- calls complete(), the payment request user interface remains
- in a pending state. At this point the user interface SHOULD NOT offer
- a cancel command because acceptance of the payment request has been
- returned. However, if something goes wrong and the developer never
- calls complete() then the user interface is blocked.
+ {{PaymentResponse}} returned to the caller, but before the caller
+ calls {{PaymentResponse/complete()}}, the payment request user
+ interface remains in a pending state. At this point the user
+ interface SHOULD NOT offer a cancel command because acceptance of the
+ payment request has been returned. However, if something goes wrong
+ and the developer never calls {{PaymentResponse/complete()}} then the
+ user interface is blocked.
For this reason, implementations MAY impose a timeout for developers
- to call complete(). If the timeout expires then the
- implementation will behave as if complete() was called with no
- arguments.
+ to call {{PaymentResponse/complete()}}. If the timeout expires then
+ the implementation will behave as if {{PaymentResponse/complete()}}
+ was called with no arguments.
- The complete(|result|) method MUST act as
- follows:
+ The {{PaymentResponse/complete()}} method MUST act as follows:
Let |serializedData| be the result of [=serialize a JavaScript
+ value to a JSON string|serialize=]
+ |details|.{{PaymentCompleteDetails/data}} into a JSON string.
+
+
If serializing [=exception/throws=] an exception, return a
+ promise rejected with that exception.
+
+
If required by the specification that defines the
+ |response|.{{PaymentResponse/methodName}}:
+
+
Let |json| be the result of calling `JSON`'s {{JSON/parse()}}
+ with |serializedData|.
+
+
Let |idl| be the result of [=converted to an IDL
+ value|converting=] |json| to an IDL value of the type specified
+ by the specification that defines the
+ |response|.{{PaymentResponse/methodName}}.
+
+
If the conversion to an IDL value [=exception/throws=] an
+ [=exception=], return a promise rejected with that
+ exception.
+
+
If required by the specification that defines the
+ |response|.{{PaymentResponse/methodName}}, validate the members
+ of |idl|. If a member's value is invalid, return a promise
+ rejected with a {{TypeError}}.
+
+
+
+
+
Set |response|.{{PaymentResponse/[[complete]]}} to true.
Return |promise| and perform the remaining steps in
parallel.
@@ -3487,8 +2916,8 @@
Otherwise:
Close down any remaining user interface. The user
- agent MAY use the value |result| to influence the user
- experience.
+ agent MAY use the value |result| and |serializedData| to
+ influence the user experience.
- Instances of PaymentResponse are created with the internal
- slots in the following table:
+ Instances of {{PaymentResponse}} are created with the [=internal
+ slots=] in the following table:
-
+
Internal Slot
@@ -3528,10 +2957,11 @@
[[\complete]]
-
+
Is true if the request for payment has completed (i.e.,
- complete() was called, or there was a fatal error that
- made the response not longer usable), or false otherwise.
+ {{PaymentResponse/complete()}} was called, or there was a fatal
+ error that made the response not longer usable), or false
+ otherwise.
@@ -3540,7 +2970,7 @@
The {{PaymentRequest}} instance that instantiated this
- PaymentResponse.
+ {{PaymentResponse}}.
@@ -3556,48 +2986,160 @@
-
+
- PaymentRequest and iframe elements
+ Shipping and billing addresses
- To indicate that a cross-origin iframe is allowed to invoke the
- payment request API, the {{ HTMLIFrameElement.allowPaymentRequest }}
- attribute can be specified on the iframe element. See for details of how {{
- HTMLIFrameElement.allowPaymentRequest }} and [[[feature-policy]]]
- interact.
+ The {{PaymentRequest}} interface allows a merchant to request from the
+ user [=physical address|physical addresses=] for the purposes of
+ shipping and/or billing. A shipping address and billing
+ address are [=physical address|physical addresses=].
+ The members of the {{AddressErrors}} dictionary represent validation
+ errors with specific parts of a [=physical address=]. Each dictionary
+ member has a dual function: firstly, its presence denotes that a
+ particular part of an address is suffering from a validation error.
+ Secondly, the string value allows the developer to describe the
+ validation error (and possibly how the end user can fix the error).
+
+
+ Developers need to be aware that users might not have the ability to
+ fix certain parts of an address. As such, they need to be mindful not
+ to ask the user to fix things they might not have control over.
+
+
+
+ addressLine member
+
+
+ Denotes that the [=physical address/address line=] has a validation
+ error. In the user agent's UI, this member corresponds to the input
+ field that provided the {{ContactAddress}}'s
+ {{ContactAddress/addressLine}} attribute's value.
+
+
+ city member
+
+
+ Denotes that the [=physical address/city=] has a validation error.
+ In the user agent's UI, this member corresponds to the input field
+ that provided the {{ContactAddress}}'s {{ContactAddress/city}}
+ attribute's value.
+
+
+ country member
+
+
+ Denotes that the [=physical address/country=] has a validation
+ error. In the user agent's UI, this member corresponds to the input
+ field that provided the {{ContactAddress}}'s
+ {{ContactAddress/country}} attribute's value.
+
+
+ dependentLocality member
+
+
+ Denotes that the [=physical address/dependent locality=] has a
+ validation error. In the user agent's UI, this member corresponds
+ to the input field that provided the {{ContactAddress}}'s
+ {{ContactAddress/dependentLocality}} attribute's value.
+
+
+ organization member
+
+
+ Denotes that the [=physical address/organization=] has a validation
+ error. In the user agent's UI, this member corresponds to the input
+ field that provided the {{ContactAddress}}'s
+ {{ContactAddress/organization}} attribute's value.
+
+
+ phone member
+
+
+ Denotes that the [=physical address/phone number=] has a validation
+ error. In the user agent's UI, this member corresponds to the input
+ field that provided the {{ContactAddress}}'s
+ {{ContactAddress/phone}} attribute's value.
+
+
+ postalCode member
+
+
+ Denotes that the [=physical address/postal code=] has a validation
+ error. In the user agent's UI, this member corresponds to the input
+ field that provided the {{ContactAddress}}'s
+ {{ContactAddress/postalCode}} attribute's value.
+
+
+ recipient member
+
+
+ Denotes that the [=physical address/recipient=] has a validation
+ error. In the user agent's UI, this member corresponds to the input
+ field that provided the {{ContactAddress}}'s
+ {{ContactAddress/addressLine}} attribute's value.
+
+
+ region member
+
+
+ Denotes that the [=physical address/region=] has a validation
+ error. In the user agent's UI, this member corresponds to the input
+ field that provided the {{ContactAddress}}'s
+ {{ContactAddress/region}} attribute's value.
+
+
+ sortingCode member
+
+
+ The [=physical address/sorting code=] has a validation error. In
+ the user agent's UI, this member corresponds to the input field
+ that provided the {{ContactAddress}}'s
+ {{ContactAddress/sortingCode}} attribute's value.
+
- This specification defines a policy-controlled feature identified by
- the string "payment". Its default allowlist is
- 'self'.
+ This specification defines a [=policy-controlled feature=] identified
+ by the string "payment"
+ [[permissions-policy]]. Its [=policy-controlled feature/default
+ allowlist=] is [=default allowlist/'self'=].
-
+
+
@@ -3607,7 +3149,7 @@
Summary
-
+
Event name
@@ -3622,21 +3164,6 @@
Target
-
-
- merchantvalidation
-
-
- {{MerchantValidationEvent}}
-
-
- The user agent requires the merchant to perform merchant
- validation.
-
- The event constructing steps, which take a
- {{MerchantValidationEvent}} |event|, are as follows:
-
-
-
Let |base:URL| be the [=context object|event=]’s relevant
- settings object’s [=environment settings object/api base URL=].
-
-
Let
- |validationURL:URL| be the result of [=URL parser|URL parsing=]
- |eventInitDict|["validationURL"] and |base|.
-
-
If |validationURL| is failure, throw a {{TypeError}}.
-
-
Initialize |event|.validationURL attribute to
- |validationURL|.
-
-
If |eventInitDict|["methodName"] is not the empty
- string, run the steps to validate a payment method
- identifier with |eventInitDict|["methodName"]. If it
- returns false, then throw a {{RangeError}} exception. Optionally,
- inform the developer that the payment method identifier is invalid.
-
Initialize |event|.{{[[waitForUpdate]]}} to false.
-
-
-
-
-
- validationURL attribute
-
-
- A URL from which a developer can fetch payment
- handler-specific verification data. By then passing that data
- (or a promise that resolves with that data) to complete(),
- the user agent can verify that the payment request is from an
- authorized merchant.
-
-
- When getting, returns the value it was initialized with.
-
-
-
-
- complete() method
-
-
- The {{MerchantValidationEvent}}'s
- complete(|merchantSessionPromise|) method MUST act as
- follows:
-
- A URL from which a developer would fetch payment
- handler-specific verification data.
-
-
-
-
-
+
PaymentMethodChangeEvent interface
@@ -3886,24 +3240,23 @@
methodDetails attribute
-
+
When getting, returns the value it was initialized with. See
- methodDetails member of PaymentMethodChangeEventInit
- for more information.
+ {{PaymentMethodChangeEventInit/methodDetails}} member of
+ {{PaymentMethodChangeEventInit}} for more information.
methodName attribute
-
+
When getting, returns the value it was initialized with. See
- methodName member of PaymentMethodChangeEventInit for
- more information.
+ {{PaymentMethodChangeEventInit/methodName}} member of
+ {{PaymentMethodChangeEventInit}} for more information.
the [=Event/constructor=] of {{PaymentRequestUpdateEvent}} with
|type| and |eventInitDict|.
-
Set |event|.{{[[waitForUpdate]]}} to false.
+
Set |event|.{{PaymentRequestUpdateEvent/[[waitForUpdate]]}} to
+ false.
Return |event|.
@@ -3970,20 +3323,20 @@
- updateWith() method
+ updateWith() method
- The updateWith(|detailsPromise|) method MUST
- act as follows:
+ The {{PaymentRequestUpdateEvent/updateWith()}} with
+ |detailsPromise:Promise| method MUST act as follows:
-
Let |event:PaymentRequestUpdateEvent| be this
- {{PaymentRequestUpdateEvent}} instance.
+
Let |event:PaymentRequestUpdateEvent| be [=this=].
-
If |event|'s {{ Event.isTrusted }} attribute is false, then
+
If |event|'s {{Event/isTrusted}} attribute is false, then
[=exception/throw=] an {{"InvalidStateError"}} {{DOMException}}.
-
If |event|.[[\waitForUpdate]] is true, then
- [=exception/throw=] an {{"InvalidStateError"}} {{DOMException}}.
+
If |event|.{{PaymentRequestUpdateEvent/[[waitForUpdate]]}} is
+ true, then [=exception/throw=] an {{"InvalidStateError"}}
+ {{DOMException}}.
If |event|'s [=Event/target=] is an instance of
- PaymentResponse, let |request:PaymentRequest| be |event|'s
- [=Event/target=].[[\request]].
+ {{PaymentResponse}}, let |request:PaymentRequest| be |event|'s
+ [=Event/target=]'s {{PaymentResponse/[[request]]}}.
Otherwise, let |request:PaymentRequest| be the value of
|event|'s [=Event/target=].
@@ -4052,7 +3405,7 @@
Assert: |request| is an instance of {{PaymentRequest}}.
If |request|.{{PaymentRequest/[[state]]}} is not
- "[=state/interactive=]", then [=exception/throw=] an
+ "[=PaymentRequest/interactive=]", then [=exception/throw=] an
{{"InvalidStateError"}} {{DOMException}}.
If |request|.{{PaymentRequest/[[updating]]}} is true, then
@@ -4061,13 +3414,13 @@
Set |event|'s [=Event/stop propagation flag=] and [=Event/stop
immediate propagation flag=].
- A boolean indicating whether an updateWith()-initiated
- update is currently in progress.
+ A boolean indicating whether an
+ {{PaymentRequestUpdateEvent/updateWith()}}-initiated update is
+ currently in progress.
@@ -4118,74 +3473,11 @@
Algorithms
- When the internal slot [[\state]] of a {{PaymentRequest}} object
- is set to "[=state/interactive=]", the user agent will trigger
- the following algorithms based on user interaction.
+ When the [=internal slot=] {{PaymentRequest/[[state]]}} of a
+ {{PaymentRequest}} object is set to "[=PaymentRequest/interactive=]",
+ the user agent will trigger the following algorithms based on
+ user interaction.
-
-
- Merchant validation
-
-
- Merchant validation is the
- process by which a payment handler validates the identity of a
- merchant against some |value| (usually some cryptographic challenge
- response). Validated merchants are allowed to interface with a
- payment handler. Details of how actual validation is performed
- is outside the scope of this specification.
-
- For payment methods that support merchant validation,
- the user agent runs the request merchant validation
- algorithm. The algorithm takes a {{USVString}}
- |merchantSpecificURL|, provided by the payment handler:
-
-
-
Let |request:PaymentRequest| be the {{PaymentRequest}} object
- that the user is interacting with.
-
Set |eventInitDict|["validationURL"] to
- |validationURL|.
-
-
Set |eventInitDict|["methodName"] to |methodName|.
-
-
Let |event:MerchantValidationEvent| be the result of calling
- the [=Event/constructor=] of {{MerchantValidationEvent}} with
- "merchantvalidation" and |eventInitDict|.
-
-
Initialize |event|’s {{ Event.isTrusted }} attribute to true.
-
Can make payment algorithm
@@ -4193,25 +3485,20 @@
The can make payment algorithm checks if the user
agent supports making payment with the payment methods
- with which the {{PaymentRequest}} was constructed. It takes a boolean
- argument, |checkForInstruments|, that specifies whether the algorithm
- checks for existence of enrolled instruments in addition to
- supporting a payment method.
+ with which the {{PaymentRequest}} was constructed.
Let |request:PaymentRequest| be the {{PaymentRequest}} object on
which the method was called.
If |request|.{{PaymentRequest/[[state]]}} is not
- "[=state/created=]", then return a promise rejected with an
- {{"InvalidStateError"}} {{DOMException}}.
+ "[=PaymentRequest/created=]", then return a promise rejected
+ with an {{"InvalidStateError"}} {{DOMException}}.
This allows user agents to apply heuristics to detect and prevent
abuse of the calling method for fingerprinting purposes, such as
creating {{PaymentRequest}} objects with a variety of supported
@@ -4228,44 +3515,14 @@
parallel.
For each |paymentMethod| tuple in |request|.
- [=PaymentRequest/[[serializedMethodData]]=]:
+ {{PaymentRequest/[[serializedMethodData]]}}:
Let |identifier| be the first element in the |paymentMethod|
tuple.
-
If |checkForInstruments| is false, and the user agent has a
- payment handler that supports handling payment requests
- for |identifier|, resolve |hasHandlerPromise| with true and
- terminate this algorithm.
-
-
If |checkForInstruments| is true:
-
-
Let |data| be the result of JSON-parsing the second
- element in the |paymentMethod| tuple.
-
-
If required by the specification that defines the
- |identifier|, then [=converted to an IDL value|convert=]
- |data| to an IDL value. Otherwise, [=converted to an IDL
- value|convert=] to {{object}}.
-
-
Let |handlers| be a list of registered payment
- handlers that are authorized and can handle payment
- request for |identifier|.
-
If |hasEnrolledInstrument| is true, resolve
- |hasHandlerPromise| with true and terminate this
- algorithm.
-
-
-
-
+
If the user agent has a payment handler that supports
+ handling payment requests for |identifier|, resolve
+ |hasHandlerPromise| with true and terminate this algorithm.
@@ -4297,7 +3554,7 @@
about the recipient that the API shares with the merchant.
- For merchants, the resulting {{PaymentAddress}} object
+ For merchants, the resulting {{ContactAddress}} object
provides enough information to, for example, calculate
shipping costs, but, in most cases, not enough information
to physically locate and uniquely identify the recipient.
@@ -4313,12 +3570,12 @@
Let |redactList:list| be the empty list. Set |redactList| to
« "organization", "phone", "recipient", "addressLine" ».
Let |address:ContactAddress| be the result of running the
+ steps to [=ContactsManager/create a contactaddress from
+ user-provided input=] with |redactList|.
-
Set the {{PaymentRequest/shippingAddress}} attribute on
- |request| to |address|.
+
Set |request|.{{PaymentRequest/shippingAddress}} to
+ |address|.
Set the {{PaymentRequest/shippingOption}} attribute on
|request| to the id string of the
- PaymentShippingOption provided by the user.
+ {{PaymentShippingOption}} provided by the user.
A payment handler MAY run the payment method changed algorithm
when the user changes payment method with |methodDetails|,
@@ -4373,9 +3630,10 @@
When the user selects or changes a payment method (e.g., a credit
card), the {{PaymentMethodChangeEvent}} includes redacted billing
address information for the purpose of performing tax calculations.
- Redacted attributes include, but are not limited to, address
- line, dependent locality, organization, phone
- number, and recipient.
+ Redacted attributes include, but are not limited to, [=physical
+ address/address line=], [=physical address/dependent locality=],
+ [=physical address/organization=], [=physical address/phone number=],
+ and [=physical address/recipient=].
Let |request:PaymentRequest| be the {{PaymentRequest}} object
@@ -4389,14 +3647,15 @@
Only one update can take place at a time.
Assert: |request|.{{PaymentRequest/[[state]]}} is
- "[=state/interactive=]".
+ "[=PaymentRequest/interactive=]".
-
+
Fire an event named "paymentmethodchange" at
|request| using {{PaymentMethodChangeEvent}}, with its
- methodName attribute initialized to |methodName|, and
- its methodDetails attribute initialized to
- |methodDetails|.
+ {{PaymentMethodChangeEvent/methodName}} attribute initialized
+ to |methodName|, and its
+ {{PaymentMethodChangeEvent/methodDetails}} attribute
+ initialized to |methodDetails|.
@@ -4417,7 +3676,7 @@
one update can take place at a time.
Assert: |request|.{{PaymentRequest/[[state]]}} is
- "[=state/interactive=]".
+ "[=PaymentRequest/interactive=]".
Let |event:PaymentRequestUpdateEvent| be the result of
creating an event using the {{PaymentRequestUpdateEvent}}
@@ -4428,11 +3687,12 @@
If
- |event|.[[\waitForUpdate]] is true, disable any part of the
- user interface that could cause another update event to be fired.
+
If |event|.{{PaymentRequestUpdateEvent/[[waitForUpdate]]}} is
+ true, disable any part of the user interface that could cause another
+ update event to be fired.
If
- |event|.[[\waitForUpdate]] is true, disable any part of
- the user interface that could cause another change to the payer
- details to be fired.
+
If |event|.{{PaymentRequestUpdateEvent/[[waitForUpdate]]}} is
+ true, disable any part of the user interface that could cause
+ another change to the payer details to be fired.
Otherwise, set
+ |event|.{{PaymentRequestUpdateEvent/[[waitForUpdate]]}} to true.
@@ -4515,11 +3775,11 @@
User accepts the payment request algorithm
- The user accepts the
- payment request algorithm runs when the user accepts the
- payment request and confirms that they want to pay. It MUST queue
- a task on the user interaction task source to perform the
- following steps:
+ The user accepts the payment request algorithm runs
+ when the user accepts the payment request and confirms that they want
+ to pay. It MUST queue a task on the user interaction task
+ source to perform the following steps:
Let |request:PaymentRequest| be the {{PaymentRequest}} object
@@ -4530,12 +3790,12 @@
agent user interface SHOULD ensure that this never occurs.
If |request|.{{PaymentRequest/[[state]]}} is not
- "[=state/interactive=]", then terminate this algorithm and take no
- further action. The user agent user interface SHOULD ensure
- that this never occurs.
+ "[=PaymentRequest/interactive=]", then terminate this algorithm and
+ take no further action. The user agent user interface SHOULD
+ ensure that this never occurs.
If the {{PaymentOptions/requestShipping}} value of
- |request|.[=PaymentRequest/[[options]]=] is true, then if the
+ |request|.{{PaymentRequest/[[options]]}} is true, then if the
{{PaymentRequest/shippingAddress}} attribute of |request| is null or
if the {{PaymentRequest/shippingOption}} attribute of |request| is
null, then terminate this algorithm and take no further action. The
@@ -4547,26 +3807,26 @@
Let |response:PaymentResponse| be
|request|.{{PaymentRequest/[[response]]}} if |isRetry| is true, or a
- new PaymentResponse otherwise.
+ new {{PaymentResponse}} otherwise.
-
If |isRetry| if false, initialize the newly created |response|:
+
If |isRetry| is false, initialize the newly created |response|:
-
Set |response|.{{PaymentResponse/[[complete]]}} to false.
Set the {{PaymentResponse/requestId}} attribute value of
|response| to the value of
- |request|.[=PaymentRequest/[[details]]=].{{PaymentDetailsInit/id}}.
+ |request|.{{PaymentRequest/[[details]]}}.{{PaymentDetailsInit/id}}.
Set |request|.{{PaymentRequest/[[response]]}} to |response|.
Let |handler:payment handler| be
- |request|.[=PaymentRequest/[[handler]]=].
+ |request|.{{PaymentRequest/[[handler]]}}.
Set the {{PaymentResponse/methodName}} attribute value of
|response| to the payment method identifier of |handler|.
@@ -4576,54 +3836,54 @@
respond to a payment request.
If the {{PaymentOptions/requestShipping}} value of
- |request|.[=PaymentRequest/[[options]]=] is false, then set the
+ |request|.{{PaymentRequest/[[options]]}} is false, then set the
{{PaymentResponse/shippingAddress}} attribute value of |response| to
null. Otherwise:
-
-
Let |shippingAddress:ContactAddress| be the result of
+ [=ContactsManager/create a contactaddress from user-provided
+ input=]
-
Set the {{shippingAddress}} attribute value of |response| to
- |shippingAddress|.
+
Set the {{PaymentResponse/shippingAddress}} attribute value
+ of |response| to |shippingAddress|.
-
Set the {{shippingAddress}} attribute value of |request| to
- |shippingAddress|.
+
Set the {{PaymentResponse/shippingAddress}} attribute value
+ of |request| to |shippingAddress|.
If the {{PaymentOptions/requestShipping}} value of
- |request|.[=PaymentRequest/[[options]]=] is true, then set the
+ |request|.{{PaymentRequest/[[options]]}} is true, then set the
{{PaymentResponse/shippingOption}} attribute of |response| to the
value of the {{PaymentResponse/shippingOption}} attribute of
|request|. Otherwise, set it to null.
If the {{PaymentOptions/requestPayerName}} value of
- |request|.[=PaymentRequest/[[options]]=] is true, then set the
+ |request|.{{PaymentRequest/[[options]]}} is true, then set the
{{PaymentResponse/payerName}} attribute of |response| to the payer's
name provided by the user, or to null if none was provided.
Otherwise, set it to null.
If the {{PaymentOptions/requestPayerEmail}} value of
- |request|.[=PaymentRequest/[[options]]=] is true, then set the
+ |request|.{{PaymentRequest/[[options]]}} is true, then set the
{{PaymentResponse/payerEmail}} attribute of |response| to the payer's
email address provided by the user, or to null if none was provided.
Otherwise, set it to null.
If the {{PaymentOptions/requestPayerPhone}} value of
- |request|.[=PaymentRequest/[[options]]=] is true, then set the
+ |request|.{{PaymentRequest/[[options]]}} is true, then set the
{{PaymentResponse/payerPhone}} attribute of |response| to the payer's
phone number provided by the user, or to null if none was provided.
When setting the {{PaymentResponse/payerPhone}} value, the user agent
SHOULD format the phone number to adhere to [[E.164]].
-
Set |request|.{{PaymentRequest/[[state]]}} to "[=state/closed=]".
+
Set |request|.{{PaymentRequest/[[state]]}} to
+ "[=PaymentRequest/closed=]".
-
If |isRetry| is true, resolve |response|.[[\retryPromise]]
- with undefined. Otherwise, resolve
- |request|.{{PaymentRequest/[[acceptPromise]]}} with |response|.
+
If |isRetry| is true, resolve
+ |response|.{{PaymentResponse/[[retryPromise]]}} with undefined.
+ Otherwise, resolve |request|.{{PaymentRequest/[[acceptPromise]]}}
+ with |response|.
@@ -4643,11 +3903,12 @@
that the user is interacting with.
If |request|.{{PaymentRequest/[[state]]}} is not
- "[=state/interactive=]", then terminate this algorithm and take no
- further action. The user agent user interface SHOULD ensure
- that this never occurs.
+ "[=PaymentRequest/interactive=]", then terminate this algorithm and
+ take no further action. The user agent user interface SHOULD
+ ensure that this never occurs.
-
Set |request|.{{PaymentRequest/[[state]]}} to "[=state/closed=]".
+
Set |request|.{{PaymentRequest/[[state]]}} to
+ "[=PaymentRequest/closed=]".
Reject |response|.{{PaymentResponse/[[retryPromise]]}} with
+ |error|.
@@ -4681,14 +3944,14 @@
The update a PaymentRequest's details
- algorithm takes a PaymentDetailsUpdate |detailsPromise|,
- a {{PaymentRequest}} |request|, and |pmi| that is either a DOMString
- or null (a payment method identifier). The steps are
- conditional on the |detailsPromise| settling. If |detailsPromise|
- never settles then the payment request is blocked. The user agent
- SHOULD provide the user with a means to abort a payment request.
- Implementations MAY choose to implement a timeout for pending updates
- if |detailsPromise| doesn't settle in a reasonable amount of time.
+ algorithm takes a {{PaymentDetailsUpdate}} |detailsPromise|, a
+ {{PaymentRequest}} |request|, and |pmi| that is either a DOMString or
+ null (a payment method identifier). The steps are conditional
+ on the |detailsPromise| settling. If |detailsPromise| never settles
+ then the payment request is blocked. The user agent SHOULD provide
+ the user with a means to abort a payment request. Implementations MAY
+ choose to implement a timeout for pending updates if |detailsPromise|
+ doesn't settle in a reasonable amount of time.
In the case where a timeout occurs, or the user manually aborts, or
@@ -4716,35 +3979,36 @@
Let |details| be the result of [=converted to an IDL
- value|converting=] |value| to a PaymentDetailsUpdate
- dictionary. If this [=exception/throw=] an exception, abort
- the update with |request| and with the thrown exception.
+
+
Let |details:PaymentDetailsUpdate| be the result of
+ [=converted to an IDL value|converting=] |value| to a
+ {{PaymentDetailsUpdate}} dictionary. If this [=exception/throw=]
+ an exception, abort the update with |request| and with the
+ thrown exception.
If the total
- member of |details| is present, then:
+
If the {{PaymentDetailsUpdate/total}} member of |details|
+ is present, then:
Check and canonicalize total amount
- |details|.total.{{PaymentItem/amount}}. If an
- exception is thrown, then abort the update with
- |request| and that exception.
+ |details|.{{PaymentDetailsUpdate/total}}.{{PaymentItem/amount}}.
+ If an exception is thrown, then abort the update
+ with |request| and that exception.
-
If the displayItems member of |details| is
- present, then for each |item| in
- |details|.displayItems:
+
If the {{PaymentDetailsBase/displayItems}} member of
+ |details| is present, then for each |item| in
+ |details|.{{PaymentDetailsBase/displayItems}}:
If the shippingOptions member of |details| is
- present, and
- |request|.[=PaymentRequest/[[options]]=].{{PaymentOptions/requestShipping}}
+
If the {{PaymentDetailsBase/shippingOptions}} member of
+ |details| is present, and
+ |request|.{{PaymentRequest/[[options]]}}.{{PaymentOptions/requestShipping}}
is true, then:
Let |seenIDs| be an empty set.
For each |option| in
- |details|.shippingOptions:
+ |details|.{{PaymentDetailsBase/shippingOptions}}:
If the total member of |modifier| is
- present, then:
+
If the {{PaymentDetailsModifier/total}} member of
+ |modifier| is present, then:
Check and canonicalize total amount
- |modifier|.total.{{PaymentItem/amount}}.
+ |modifier|.{{PaymentDetailsModifier/total}}.{{PaymentItem/amount}}.
If an exception is thrown, then abort the
update with |request| and that exception.
If the
+ {{PaymentDetailsModifier/additionalDisplayItems}}
+ member of |modifier| is present, then for each
+ {{PaymentItem}} |item| in
+ |modifier|.{{PaymentDetailsModifier/additionalDisplayItems}}:
If the {{PaymentDetailsModifier/data}} member of
|modifier| is missing, let |serializedData| be null.
- Otherwise, let |serializedData| be the result of
- JSON-serializing
- |modifier|.{{PaymentDetailsModifier/data}} into a
- string. If JSON-serializing throws an
- exception, then abort the update with
- |request| and that exception.
+ Otherwise, let |serializedData| be the result of
+ [=serialize a JavaScript value to a JSON
+ string|serialize=]
+ |modifier|.{{PaymentDetailsModifier/data}} into a
+ JSON string. If it throws an exception, then abort
+ the update with |request| and that exception.
Add |serializedData| to |serializedModifierData|.
@@ -4854,49 +4119,49 @@
-
If the
- paymentMethodErrors member is present and |identifier| is
- not null:
+
If the {{PaymentDetailsUpdate/paymentMethodErrors}} member is
+ present and |identifier| is not null:
If required by the specification that defines the |pmi|,
then [=converted to an IDL value|convert=]
- paymentMethodErrors to an IDL value.
+ {{PaymentDetailsUpdate/paymentMethodErrors}} to an IDL value.
The payment handler SHOULD display an error for
- each relevant erroneous field of paymentMethodErrors.
+ each relevant erroneous field of
+ {{PaymentDetailsUpdate/paymentMethodErrors}}.
Update the {{PaymentRequest}} using the new details:
-
If the total
- member of |details| is present, then:
+
If the {{PaymentDetailsUpdate/total}} member of |details|
+ is present, then:
Set
- |request|.[=PaymentRequest/[[details]]=].total
- to |details|.total.
+ |request|.{{PaymentRequest/[[details]]}}.{{PaymentDetailsInit/total}}
+ to |details|.{{PaymentDetailsUpdate/total}}.
-
If the displayItems member of |details| is
- present, then:
+
If the {{PaymentDetailsBase/displayItems}} member of
+ |details| is present, then:
Set
- |request|.[=PaymentRequest/[[details]]=].displayItems
- to |details|.displayItems.
+ |request|.{{PaymentRequest/[[details]]}}.{{PaymentDetailsBase/displayItems}}
+ to |details|.{{PaymentDetailsBase/displayItems}}.
-
If the shippingOptions member of |details| is
- present, and
- |request|.[=PaymentRequest/[[options]]=].{{PaymentOptions/requestShipping}}
+
If the {{PaymentDetailsBase/shippingOptions}} member of
+ |details| is present, and
+ |request|.{{PaymentRequest/[[options]]}}.{{PaymentOptions/requestShipping}}
is true, then:
Set
- |request|.[=PaymentRequest/[[details]]=].shippingOptions
+ |request|.{{PaymentRequest/[[details]]}}.{{PaymentDetailsBase/shippingOptions}}
to |shippingOptions|.
Set the value of |request|'s
@@ -4905,15 +4170,15 @@
-
If the modifiers member of |details| is present,
- then:
+
If the {{PaymentDetailsBase/modifiers}} member of
+ |details| is present, then:
Set
- |request|.[=PaymentRequest/[[details]]=].modifiers
- to |details|.modifiers.
+ |request|.{{PaymentRequest/[[details]]}}.{{PaymentDetailsBase/modifiers}}
+ to |details|.{{PaymentDetailsBase/modifiers}}.
Set
- |request|.[=PaymentRequest/[[serializedModifierData]]=]
+ |request|.{{PaymentRequest/[[serializedModifierData]]}}
to |serializedModifierData|.
@@ -4921,9 +4186,9 @@
If
- |request|.[=PaymentRequest/[[options]]=].{{PaymentOptions/requestShipping}}
+ |request|.{{PaymentRequest/[[options]]}}.{{PaymentOptions/requestShipping}}
is true, and
- |request|.[=PaymentRequest/[[details]]=].shippingOptions
+ |request|.{{PaymentRequest/[[details]]}}.{{PaymentDetailsBase/shippingOptions}}
is empty, then the developer has signified that there are
no valid shipping options for the currently-chosen
shipping address (given by |request|'s
@@ -4944,19 +4209,20 @@
member is present, the user agent SHOULD display an error
specifically for each erroneous field of the shipping
address. This is done by matching each present member of
- the AddressErrors to a corresponding input field
- in the shown user interface.
+ the {{AddressErrors}} to a corresponding input field in
+ the shown user interface.
-
- Similarly, if |details|["payerErrors"] member is
- present and |request|.[=PaymentRequest/[[options]]=]'s
+
+ Similarly, if |details|["{{payerErrors}}"] member is
+ present and |request|.{{PaymentRequest/[[options]]}}'s
{{PaymentOptions/requestPayerName}},
{{PaymentOptions/requestPayerEmail}}, or
{{PaymentOptions/requestPayerPhone}} is true, then
display an error specifically for each erroneous field.
+ Likewise, if
+ |details|.{{PaymentDetailsUpdate/paymentMethodErrors}} is
present, then display errors specifically for each
erroneous input field for the particular payment method.
@@ -4977,8 +4243,8 @@
Abort the update
- To abort the update with a {{PaymentRequest}} |request|
- and exception |exception|:
+ To abort the update with a
+ {{PaymentRequest}} |request| and exception |exception|:
Optionally, show an error message to the user when letting them
@@ -4995,20 +4261,21 @@
Reject |response|.{{PaymentResponse/[[retryPromise]]}}
+ with |exception|.
@@ -5034,107 +4301,54 @@
event.
- Consequently, the {{PaymentRequest}} moves to a "[=state/closed=]"
- state. The error is signaled to the developer through the rejection
- of the [[\acceptPromise]], i.e., the promise returned by
+ Consequently, the {{PaymentRequest}} moves to a
+ "[=PaymentRequest/closed=]" state. The error is signaled to the
+ developer through the rejection of the
+ {{PaymentRequest/[[acceptPromise]]}}, i.e., the promise returned by
{{PaymentRequest/show()}}.
-
- Similarly, abort the update occurring during retry()
- causes the [[\retryPromise]] to reject, and the
- corresponding {{PaymentRequest}}'s [[\complete]] internal
- slot will be set to true (i.e., it can no longer be used).
+
+ Similarly, abort the update occurring during
+ {{PaymentResponse/retry()}} causes the
+ {{PaymentResponse/[[retryPromise]]}} to reject, and the
+ corresponding {{PaymentResponse}}'s
+ {{PaymentResponse/[[complete]]}} [=internal slot=] will be set to
+ true (i.e., it can no longer be used).
-
-
- Validate merchant's details algorithm
-
-
- The validate merchant's details algorithm takes a
- {{Promise}} |opaqueDataPromise| and a {{PaymentRequest}} |request|.
- The steps are conditional on the |opaqueDataPromise| settling. If
- |opaqueDataPromise| never settles then the payment request is
- blocked. The user agent SHOULD provide the user with a means to abort
- a payment request. Implementations MAY choose to implement a timeout
- for pending updates if |opaqueDataPromise| doesn't settle in a
- reasonable amount of time. If an implementation chooses to implement
- a timeout, they MUST execute the steps listed below in the "upon
- rejection" path. Such a timeout is a fatal error for the payment
- request.
-
-
-
Set |request|.{{PaymentRequest/[[updating]]}} to true.
-
-
- In parallel, disable the user interface that allows the user
- to accept the payment request. This is to ensure that the payment
- is not accepted until the user interface is updated with any new
- details.
-
Otherwise, set |request|.{{PaymentRequest/[[updating]]}} to
- false.
-
-
Enable the user interface, allowing the request for payment
- to proceed.
-
-
-
-
-
Privacy and Security Considerations
-
+
User protections with show() method
To help ensure that users do not inadvertently share sensitive
credentials with an origin, this API requires that PaymentRequest's
- show() method be invoked while the relevant {{Window}} has
- [=transient activation=] (e.g., via a click or press).
+ {{PaymentRequest/show()}} method be invoked while the relevant
+ {{Window}} has [=transient activation=] (e.g., via a click or press).
To avoid a confusing user experience, this specification limits the
- user agent to displaying one at a time via the show() method.
- In addition, the user agent can limit the rate at which a page can
- call show().
+ user agent to displaying one at a time via the
+ {{PaymentRequest/show()}} method. In addition, the user agent can
+ limit the rate at which a page can call {{PaymentRequest/show()}}.
-
+
Secure contexts
- The API defined in this specification is only exposed in
- secure contexts. In practice, this
- means that this API is only available over HTTPS. This is to limit
- the possibility of payment method data (e.g., credit card numbers)
- being sent in the clear.
+ The API defined in this specification is only exposed in a [=secure
+ context=] - see also the [[[secure-contexts]]] specification for more
+ details. In practice, this means that this API is only available over
+ HTTPS. This is to limit the possibility of payment method data (e.g.,
+ credit card numbers) being sent in the clear.
@@ -5145,8 +4359,7 @@
It is common for merchants and other payees to delegate checkout and
other e-commerce activities to payment service providers through an
iframe. This API supports payee-authorized cross-origin
- iframes through [[HTML]]'s {{ HTMLIFrameElement.allowPaymentRequest
- }} attribute.
+ iframes through [[HTML]]'s [^iframe/allow^] attribute.
Payment handlers have access to both the origin that hosts the
@@ -5169,20 +4382,12 @@
How user agents match payment handlers
-
- As part of show(), the user agent typically displays a list of
- matching payment handlers that satisfy the payment
- methods accepted by the merchant and other conditions. Matching
- can take into account payment method information provided as
- input to the API, information provided by the payment method
- owner, the payment handlers registered by the user, user
- preferences, and other considerations.
-
The user agent MUST NOT share information about the user with
- a developer (e.g., the shipping address) without user consent.
+ a developer (e.g., the [=shipping address=]) without user consent.
+
+
+ In particular, the {{PaymentMethodData}}'s {{PaymentMethodData/data}}
+ and {{PaymentResponse}}'s {{PaymentResponse/details}} members allow
+ for the arbitrary exchange of data. In light of the wide range of
+ data models used by existing payment methods, prescribing data
+ specifics in this API would limit its usefulness. The
+ {{PaymentResponse/details}} member carries data from the payment
+ handler, whether Web-based (as defined by the [[[payment-handler]]])
+ or proprietary. The [=user agent=] MUST NOT support payment handlers
+ unless they include adequate user consent mechanisms (such as
+ awareness of parties to the transaction and mechanisms for
+ demonstrating the intention to share data).
The user agent MUST NOT share the values of the
{{PaymentDetailsBase/displayItems}} member or
- {{PaymentDetailsModifier/additionalDisplayItems}} member with a
- third-party payment handler without user consent.
+ {{PaymentDetailsModifier/additionalDisplayItems}} member for any
+ purpose other than to facilitate completion of the transaction.
The {{PaymentMethodChangeEvent}} enables the payee to update the
@@ -5226,22 +4444,22 @@
information as possible prior to completion of the payment.
Therefore, when a payment method defines the steps for when
a user changes payment method, it is important to minimize the
- data shared via the {{PaymentMethodChangeEvent}}'s methodDetails attribute. Requirements
+ data shared via the {{PaymentMethodChangeEvent}}'s
+ {{PaymentMethodChangeEvent/methodDetails}} attribute. Requirements
and approaches for minimizing shared data are likely to vary by
payment method and might include:
Use of a "|redactList|" for physical addresses. The
- current specification makes use of a "|redactList|" to redact the
- address line, organization, phone number, and
- recipient from a shippingAddress.
+ current specification makes use of a "|redactList|" to redact the
+ [=physical address/address line=], [=physical address/organization=],
+ [=physical address/phone number=], and [=physical address/recipient=]
+ from a {{PaymentRequest/shippingAddress}}.
Support for instructions from the payee identifying specific
elements to exclude or include from the payment method
- response data (returned through PaymentResponse.|details|).
- The payee might provide these instructions via
+ response data (returned through {{PaymentResponse}}.|details|). The
+ payee might provide these instructions via
PaymentMethodData.|data|, enabling a payment method
definition to evolve without requiring changes to the current API.
@@ -5254,33 +4472,19 @@
with a merchant.
-
-
- Merchant Validation
-
-
- It is important that the validationURL in a
- {{MerchantValidationEvent}} does not expose personally identifying
- information to unauthorized parties.
-
-
canMakePayment() protections
-
- The canMakePayment() and hasEnrolledInstrument()
- methods have the potential to expose user information that could be
- abused for fingerprinting purposes. User agents are expected to
- protect the user from abuse of the method. For example, user agents
- can reduce user fingerprinting by:
+
+ The {{PaymentRequest/canMakePayment()}} method provides feature
+ detection for different payment methods. It may become a
+ fingerprinting vector if in the future, a large number of payment
+ methods are available. User agents are expected to protect the user
+ from abuse of the method. For example, user agents can reduce user
+ fingerprinting by:
These rate-limiting techniques intend to increase the cost associated
with repeated calls, whether it is the cost of managing multiple
- eTLDs or the user experience friction of opening multiple windows
- (tabs or pop-ups).
+ [=host/registrable domains=] or the user experience friction of
+ opening multiple windows (tabs or pop-ups).
+
+
+
+
+ User activation requirement
+
+
+ If the user agent does not require user activation as part of the
+ {{PaymentRequest/show()}} method, some additional security mitigations
+ should be considered. Not requiring user activation increases the risk
+ of spam and click-jacking attacks, by allowing a Payment Request UI
+ to be initiated without the user interacting with the page immediately
+ beforehand.
+
+
+ In order to mitigate spam, the user agent may decide to enforce a user
+ activation requirement after some threshold, for example after the
+ user has already been shown a Payment Request UI without a user
+ activation on the current page. In order to mitigate click-jacking
+ attacks, the user agent may implement a time threshold in which clicks
+ are ignored immediately after a dialog is shown.
+
+
+ Another relevant mitigation exists in step 6 of
+ {{PaymentRequest/show()}}, where the document must be visible in order
+ to initiate the user interaction.
@@ -5324,31 +4555,13 @@
This specification relies on several other underlying specifications.
-
- ISO 3366-2
-
-
- Country subdivision
- name and country subdivision code element are
- defined in [[ISO3166-2]].
-
ECMAScript
- The terms internal
- slot, and JSON.stringify are
- defined by [[ECMASCRIPT]].
-
- The term JSON-serialize applied to
- a given object means to run the algorithm specified by the original
- value of the JSON.stringify function on the supplied object,
- passing the supplied object as the sole argument, and return the
- resulting string. This can throw an exception.
-
+ slot is defined [[ECMASCRIPT]].
@@ -5367,7 +4580,7 @@
way desired, so long as the end result is indistinguishable from the
result that would be obtained by the specification's algorithms.
-
+
User agents MAY impose implementation-specific limits on otherwise
unconstrained inputs, e.g., to prevent denial of service attacks, to
guard against running out of memory, or to work around
@@ -5395,7 +4608,17 @@
The mission of the Web Payments Working Group is to make payments easier and more secure on the Web.
-
-
The group is chartered to develop multiple technologies. The current document describes a set of
- technologies —the Payment Request Architecture— that, together,
- provide merchants with a consistent way to request payment information
- from the user, aided by a user agent.
-
-
The focus of the Payment Request Architecture is to provide
- an abstract interface between a web page and a Payment
- App to facilitate a payment transaction. This is expected
- to streamline checkout and help reduce shopping cart
- abandonment, as well as make it easier to use new payment methods on the Web. This document
- does not describe a complete architecture for end-to-end payments on the Web.
-
-
-
This document does not address the full set of deliverables of the Web Payments Working Group.
-
-
-
-
- The working group maintains a
- list of all bug reports that the group has not yet addressed.
- This draft highlights some of the pending issues that are still to be discussed in the working
- group. No decision has been taken on the outcome of these issues including whether they are valid.
- Pull requests with proposed specification text for outstanding issues are strongly encouraged.
-
This (imperfect) overview of the anticipated user experience will help explain the architecture:
-
-
-
At the end of shopping on a merchant site, the user pushes the “buy” button.
-
The merchant site calls the payment API with purchase amount, currency, accepted payment methods (e.g., Visa, Paypal, Bitcoin), and any custom data for those payment methods.
-
The user agent determines the intersection of merchant-accepted payment methods and user-registered payment methods. The merchant can (optionally) use the API to capture shipping information through the same user experience.
-
The user selects a payment app to pay, and carries out any app-supported activities as needed, such as authentication.
-
Assuming the payment is authorized, the payment app returns payment method-specific data through the user agent to the merchant site.
-
Depending on the payment method, this data will either enable the merchant to be paid, or signal that the merchant has already been paid.
-
-
-
-
-
Components
-
-
- The following are key components of the Payment Request Architecture. These
- components would normally sit between
- the Payment Service Providers (PSPs) of the payer and
- payee. Different implementations of this architecture may result in components running on entirely
- different physical systems communicating over network boundaries or, in the other extreme, the same
- physical system assuming the role of a number of components with communication simply crossing
- process boundaries. For some payment schemes such as Bitcoin, the components communicate directly into the
- scheme's infrastructure.
-
-
-
-
Payment Apps
-
-
A Payment App is software used to pay. Banks, merchants,
- mobile operators, and anyone else who wants to will make
- these available. User agents are also likely to act as basic
- payment apps, storing some information on behalf of the
- user, as they already do today with passwords. We expect
- payment apps will increase security and privacy by giving
- users more control over what they share over the
- network. Payment apps will distinguish themselves through
- the features and services they provide beyond the standard
- API, such as strong user authentication, loyalty program
- integration, back-channel communications with the merchant
- for fraud analytics, and so on.
-
-
Payment apps should be able to run on desktops, mobile
- devices, televisions and other devices and operating
- systems. The execution environment for the Payment App is
- called the "Payment App Host." The Payment App Host may be
- tightly integrated with other components such as the
- Payment Mediator or may be one or more separate systems
- hosting individual Payment Apps or a combination of
- these.
-
-
As part of facilitating payment, a Payment App may
- render a user interface and/or take advantage of one or
- more other IO channels for payer or third-party
- interaction (e.g., payment service provider). In some
- cases and where supported by a payment method, a Payment
- App may be able to facilitate a payment without immediate
- user interaction based on prior payer consent. (Example: A
- Web of Things scenario where the payer is a machine
- capable of executing payments in accordance with
- predefined rules and logic).
-
-
The composition of a Payment App will be platform and
- deployment dependent and many aspects of how the Payment App
- communicates with the host, interacts with the payer and
- payee, and communicates with third-party services will be
- determined by the implementer who provides the Payment App
- Host, as an execution environment for the app, and the
- Payment Mediator, that mediates all interactions between the
- Payment App and other components.
-
-
- When a user registers a new payment instrument, how is that payment
- instrument shared between different browser brands? For example, if I
- register a Visa debit card issued by my bank in Google Chrome on my
- laptop, when I go to purchase something using my mobile phone, is
- that same debit card available to me via my Firefox web browser
- (assuming I've authenticated in some way with both browsers)?
-
-
-
-
Payment Methods
-
-
Each payment app will support one or more payment methods. A payment method is a system and set of rules for payments. We are designing the API to support the broadest possible array of payment methods. When a merchant accepts a given payment method, the assumption is that the merchant will know how to process the data returned by the payment app for that payment method.
-
-
Each payment method is identified by a Payment Method Identifier.
- The payment mediator compares payment method identifiers to determine which
- payment methods to offer the user. Payment Method Identifiers will support distributed extensibility, meaning that there does
- not need to be a central machine-readable registry to discover or register payment methods.
-
-
The information required to use a Payment Method is called Payment Method Data. For a given payment method within a payment app, a user may have multiple instances of payment method data. Examples: a personal credit card (PAN, expiration data, CVV) and a business credit card, or multiple Bitcoin accounts.
-
-
-
-
Payment Mediators
-
-
-
The Payment Mediator fulfills a number of roles:
-
-
It helps determine which payer Payment Apps can be used to fulfill the payment request given the payee's accepted payment methods.
-
It helps the payer choose one (typically with explicit interaction or prior consent).
-
It passes payment request data to the payer's selected Payment App.
-
-
-
We expect that user agents will primarily act as payment mediators in this architecture.
-
-
-
-
-
Specifications
-
-
The Payment Request Architecture organizes the above concepts into several component specifications
- so that they can be discussed and moved forward independently. The
- Payment Method Identifiers specification is the only
- common dependency. The following diagram shows the references between different specifications that describe
- the Payment Request Architecture. The arrows show normative references pointing from the referring
- document to the referenced document.
-
-
-
- Relationship among different specifications in the Payment Request system
-
-
-
-
Payment Method Identifiers
-
The Payment Method Identifiers [[METHOD-IDENTIFIERS]] specification defines the format of
- Payment Method Identifiers.
-
-
- If we choose to support well-known short strings for payment methods then we will need to
- determine where to define them. We may choose to define these well-known strings in a
- formal specification.
-
-
-
-
-
-
Payment Request API
-
- The Payment Request API [[PAYMENT-REQUEST-API]] specification defines the API that makes a
- user agent the conduit for messages exchanged between web pages (or applications) and payment apps.
- The web page supplies a list of payment methods accepted by the merchant. The Payment Mediator
- matches those against payment methods supported by the user’s registered Payment Apps.
-
-
- One principle of the Payment Request system is that when a merchant web site declares
- that it accepts a given payment method then it must know how to process the resulting
- response.
-
-
-
-
-
Payment Method Specifications
-
- The Payment Request API specification has no intrinsic knowledge of the payment
- methods available. When a transaction is enacted by the user through the API a JSON object
- containing the relevant information necessary to process the transaction is returned. The
- format of this "message" is defined specifically for the payment method and might be private
- to that method.
-
-
We expect some message definitions to be shared amongst different
- payment apps. One example is the [[BASIC-CARD-PAYMENTS]], which defines a payment
- method identifier, method-specific request data, and method-specific response data
- for a basic card payment method. We expect this specification to be a model for other
- payment method specifications.
-
-
-
-
Payment App Registration Specifications
-
- There is an open question within the working group about what registration scenarios
- should be supported by specifications from the group. See the Payment App Registration explainer and registration scenarios.
-
-
-
-
-
-
-
Glossary
-
-
- It has been suggested that all Web Payments specifications should use
- common terminology. There is a Web Payments Interest Group glossary that
- contains common terminology that could be integrated into this
- specification and automatically kept in sync via ReSpec's dynamic
- terminology import feature.
-
-
-
-
Payment Method
-
A way of paying. A system and set of rules for payments. A payment app may support one or
- more payment methods. Examples: cleartext-visa, tokenized-mastercard, bobspay.com (a fictitious payment service).
-
-
Payment Method Identifier
-
A way to identify a payment method. The payment mediator compares payment method identifiers to determine which
- payment methods to offer the user.
-
-
Payment App
-
- A piece of software that enables a payer to make payments. A payment app may support one or more
- payment methods.
-
-
Payment Mediator
-
- Software that matches payee-accepted payment methods and user-registered payment methods, and
- offers a choice to the user for selection.
-
-
Payment Method Data
-
- The data describing an instance of a payment method. For example, for the cleartext-visa payment
- method this might be the card primary account number (PAN), expiry date, and CVV.
-
-
-
-
-
Relationship to Previous Concepts
-
-
This architecture uses concepts like "payment app" because the Working Group has found it challenging to adopt the "digital wallet" metaphor for several reasons:
-
-
-
- In the physical world it is not practical for users to have multiple wallets. On the Web this is
- possible and for there to be copies of the same payment method data in more than one wallet.
-
In the physical world the process of deciding how to pay is not done by the wallet, it is done by
- the user. On the Web the process of selection can be facilitated by digital algorithms that are capable
- of processing complex data and relationships to assist the user in deciding how to pay.
-
- In the physical world a user selects a payment method data directly because this what is held in their
- wallet. On the Web the user is more likely to pick some abstraction of their payment method data that
- may itself represent multiple payment method instances.
-
-
-
There is not a one-to-one mapping from the previous concepts to the current ones, as the modeling is fundamentally different. Here is how previous and current concepts relate:
-
-
-
-
Current
-
Previous
-
Short definition
-
-
-
Payment App
-
Digital Wallet, Payment Instrument
-
An application, registered by the payer, that supports processing payment
- requests and returning payment responses for one or more payment methods.
-
-
-
Payment Method
-
Payment Scheme
-
A system and set of rules for payments.
-
-
-
Payment Mediator
-
Digital Wallet, Payment Instrument
-
A piece of software that coordinates messages between sellers and Payment apps.
- 
-