This specification defines capabilities that enable Web applications to @@ -101,11 +101,13 @@
An origin may implement a payment app with more than one service worker - and therefore multiple payment handlers may be registered per - origin. The handler that is invoked is determined by the selection made - by the user. + and therefore multiple Web-based payment handlers may be + registered per origin. The handler that is invoked is determined by the + selection made by the user.
- A payment handler is a Web application that can handle a + A Web-based payment handler is a Web application based + [=payment handler=]; that is, a Web application that can handle a request for payment on behalf of the user.
- The logic of a payment handler is driven by the payment methods that - it supports. Some payment methods expect little to no processing by - the payment handler which simply returns payment card details in the - response. It is then the job of the payee website to process the - payment using the returned data as input. + The logic of a web-based payment handler is driven by the payment + methods that it supports. Some payment methods expect little to no + processing by the web-based payment handler which simply returns + payment card details in the response. It is then the job of the payee + website to process the payment using the returned data as input.
In contrast, some payment methods, such as a crypto-currency payments - or bank originated credit transfers, require that the payment handler - initiate processing of the payment. In such cases the payment handler - will return a payment reference, endpoint URL or some other data that - the payee website can use to determine the outcome of the payment (as - opposed to processing the payment itself). + or bank originated credit transfers, require that the web-based + payment handler initiate processing of the payment. In such cases the + web-based payment handler will return a payment reference, endpoint + URL or some other data that the payee website can use to determine the + outcome of the payment (as opposed to processing the payment itself).
Handling a payment request may include numerous interactions: with @@ -210,11 +214,12 @@
This specification does not address these activities that occur - between the payment handler accepting the {{PaymentRequestEvent}} and - the payment handler returning a response. All of these activities - which may be required to configure the payment handler and handle the - payment request, are left to the implementation of the payment - handler, including: + between the web-based payment handler accepting the + {{PaymentRequestEvent}} and the web-based payment handler returning a + response. All of these activities which may be required to configure + the web-based payment handler and handle the payment request, are + left to the implementation of the web-based payment handler, + including:
- One registers a payment handler with the user agent through a + One registers a web-based payment handler with the user agent through a just-in-time (JIT) registration mechanism.
- If a payment handler is not registered when a merchant invokes - {{PaymentRequest/show()}} method, a user agent may allow the user to - register this payment handler during the transaction ("just-in-time"). + If a web-based payment handler is not registered when a merchant + invokes {{PaymentRequest/show()}} method, a user agent may allow the + user to register this web-based payment handler during the transaction + ("just-in-time").
The remaining content of this section is non-normative.
- A user agent may perform just-in-time installation by deriving payment - handler information from the payment method manifest that is - found through the URL-based payment method identifier that the - merchant requested. + A user agent may perform just-in-time installation by deriving + web-based payment handler information from the payment method + manifest that is found through the URL-based payment method + identifier that the merchant requested.
- This section describes the functionality available to a payment handler - to manage its own properties. + This section describes the functionality available to a web-based + payment handler to manage its own properties.
- The paymentManager attribute exposes payment handler - management functionality. + The paymentManager attribute exposes web-based payment + handler management functionality.
- The {{PaymentManager}} is used by payment handlers to manage - their supported delegations. + The {{PaymentManager}} is used by Web-based payment handlers to + manage their supported delegations.
- When displaying payment handler name and icon, the user agent may - use this string to improve the user experience. For example, a user - hint of "**** 1234" can remind the user that a particular card is - available through this payment handler. + When displaying web-based payment handler name and icon, the user + agent may use this string to improve the user experience. For + example, a user hint of "**** 1234" can remind the user that a + particular card is available through this web-based payment handler.
- This method allows a payment handler to asynchronously - declare its supported PaymentDelegation list. + This method allows a Web-based payment handler to + asynchronously declare its supported PaymentDelegation list.
- If the payment handler supports CanMakePaymentEvent, the - user agent may use it to help with filtering of the available - payment handlers. + If the Web-based payment handler supports + CanMakePaymentEvent, the user agent may use it to help + with filtering of the available web-based payment handlers.
Implementations may impose a timeout for developers to respond to the @@ -419,7 +429,7 @@
The CanMakePaymentEvent is used to as a signal for whether the - payment handler is able to respond to a payment request. + web-based payment handler is able to respond to a payment request.
[Exposed=ServiceWorker]
@@ -433,8 +443,8 @@
respondWith() method
- This method is used by the payment handler as a signal for whether
- it can respond to a payment request.
+ This method is used by the web-based payment handler as a signal for
+ whether it can respond to a payment request.
@@ -485,9 +495,10 @@
Filtering of Payment Handlers
- Given a PaymentMethodData and a payment handler that matches on
- payment method identifier, this algorithm returns
- true if this payment handler can be used for payment:
+ Given a PaymentMethodData and a web-based payment handler that
+ matches on payment method identifier, this algorithm returns
+ true if this web-based payment handler can be used for
+ payment:
- Let methodName be the payment method identifier
@@ -497,7 +508,8 @@
PaymentMethodData.
- Let paymentHandlerOrigin be the origin of the
- {{ServiceWorkerRegistration}} scope URL of the payment handler.
+ {{ServiceWorkerRegistration}} scope URL of the web-based payment
+ handler.
- Let paymentMethodManifest be the ingested and
parsed payment method manifest for the
@@ -511,13 +523,13 @@
- Otherwise, if the URL-based payment method identifier
methodName has the same origin as
paymentHandlerOrigin, fire the CanMakePaymentEvent
- in the payment handler and return the result.
+ in the web-based payment handler and return the result.
- Otherwise, if supported origins in
paymentMethodManifest is an ordered set of [=url/origin=]
that contains the paymentHandlerOrigin, fire the
- CanMakePaymentEvent in the payment handler and return the
- result.
+ CanMakePaymentEvent in the web-based payment handler and return
+ the result.
- Otherwise, return `false`.
@@ -529,8 +541,8 @@
Invocation
- Once the user has selected a payment handler, the user agent fires a
- {{PaymentRequestEvent}} and uses the subsequent
+ Once the user has selected a web-based payment handler, the user agent
+ fires a {{PaymentRequestEvent}} and uses the subsequent
PaymentHandlerResponse to create a PaymentResponse for
[[!payment-request]].
@@ -539,8 +551,8 @@
"117">
Payment Request API supports delegation of responsibility to manage an
abort to a payment app. There is a proposal to add a
- paymentRequestAborted event to the Payment Handler interface. The event
- will have a respondWith method that takes a boolean parameter
+ paymentRequestAborted event to the Web-based Payment Handler interface.
+ The event will have a respondWith method that takes a boolean parameter
indicating if the paymentRequest has been successfully aborted.
The PaymentRequestDetailsUpdate contains the updated
total (optionally with modifiers and shipping options) and possible
errors resulting from user selection of a payment method, a shipping
- address, or a shipping option within a payment handler.
+ address, or a shipping option within a web-based payment handler.
dictionary PaymentRequestDetailsUpdate {
@@ -594,8 +606,9 @@
error member
- A human readable string that explains why the user selected payment
- method, shipping address or shipping option cannot be used.
+ A human readable string that explains why the user selected
+ web-based payment method, shipping address or shipping option cannot
+ be used.
@@ -782,8 +795,9 @@
openWindow() method
- This method is used by the payment handler to show a window to the
- user. When called, it runs the open window algorithm.
+ This method is used by the web-based payment handler to show a
+ window to the user. When called, it runs the open window
+ algorithm.
@@ -793,8 +807,8 @@
method
- This method is used by the payment handler to get updated total
- given such payment method details as the billing address. When
+ This method is used by the web-based payment handler to get updated
+ total given such payment method details as the billing address. When
called, it runs the change payment method algorithm.
@@ -805,8 +819,8 @@
method
- This method is used by the payment handler to get updated payment
- details given the shippingAddress. When called, it runs the
+ This method is used by the web-based payment handler to get updated
+ payment details given the shippingAddress. When called, it runs the
change payment details algorithm.
@@ -817,9 +831,9 @@
method
- This method is used by the payment handler to get updated payment
- details given the shippingOption identifier. When called, it runs
- the change payment details algorithm.
+ This method is used by the web-based payment handler to get updated
+ payment details given the shippingOption identifier. When called,
+ it runs the change payment details algorithm.
@@ -828,7 +842,7 @@
"respondWith(handlerResponsePromise)">respondWith() method
- This method is used by the payment handler to provide a
+ This method is used by the web-based payment handler to provide a
PaymentHandlerResponse when the payment successfully
completes. When called, it runs the Respond to PaymentRequest
Algorithm with |event| and handlerResponsePromise as
@@ -876,7 +890,8 @@
- Let registeredMethods be the set of registered
- payment method identifiers of the invoked payment handler.
+ payment method identifiers of the invoked web-based payment
+ handler.
- Create a new empty Sequence.
@@ -924,7 +939,8 @@
- Let registeredMethods be the set of registered
- payment method identifiers of the invoked payment handler.
+ payment method identifiers of the invoked web-based payment
+ handler.
- Create a new empty Sequence.
@@ -993,8 +1009,8 @@
The currently active WindowClient. This is set if a
- payment handler is currently showing a window to the user.
- Otherwise, it is null.
+ web-based payment handler is currently showing a window to the
+ user. Otherwise, it is null.
@@ -1017,12 +1033,12 @@
Upon receiving a PaymentRequest by way of PaymentRequest.show() and
- subsequent user selection of a payment handler, the user agent
- MUST run the following steps:
+ subsequent user selection of a web-based payment handler, the user
+ agent MUST run the following steps:
- Let registration be the {{ServiceWorkerRegistration}}
- corresponding to the payment handler selected by the user.
+ corresponding to the web-based payment handler selected by the user.
- If registration is not found, reject the {{Promise}}
that was created by
- Wait for all of the promises in the extend lifetime
promises of dispatchedEvent to resolve.
- - If the payment handler has not provided a
+
- If the Web-based payment handler has not provided a
PaymentHandlerResponse, reject the {{Promise}} that was
created by PaymentRequest.show() with an
@@ -1118,29 +1134,29 @@
- Windows
+ Windows
- An invoked payment handler may or may not need to display information
- about itself or request user input. Some examples of potential payment
- handler display include:
+ An invoked web-based payment handler may or may not need to display
+ information about itself or request user input. Some examples of
+ potential web-based payment handler display include:
- - The payment handler opens a window for the user to provide an
- authorization code.
+
- The web-based payment handler opens a window for the user to provide
+ an authorization code.
- - The payment handler opens a window that makes it easy for the user
- to confirm payment using default information for that site provided
- through previous user configuration.
+
- The web-based payment handler opens a window that makes it easy for
+ the user to confirm payment using default information for that site
+ provided through previous user configuration.
- - When first selected to pay in a given session, the payment handler
- opens a window. For subsequent payments in the same session, the
- payment handler (through configuration) performs its duties without
- opening a window or requiring user interaction.
+
- When first selected to pay in a given session, the web-based payment
+ handler opens a window. For subsequent payments in the same session, the
+ web-based payment handler (through configuration) performs its duties
+ without opening a window or requiring user interaction.
- A payment handler that requires visual display and user
+ A Web-based payment handler that requires visual display and user
interaction, may call openWindow() to display a page to the user.
@@ -1148,8 +1164,8 @@
{{PaymentRequestEvent}}, they SHOULD render the window in a way that is
consistent with the flow and not confusing to the user. The resulting
window client is bound to the tab/window that initiated the
- PaymentRequest. A single payment handler SHOULD NOT be
- allowed to open more than one client window using this method.
+ PaymentRequest. A single Web-based payment handler SHOULD
+ NOT be allowed to open more than one client window using this method.
@@ -1182,8 +1198,8 @@
{{Promise}} rejected with a {{TypeError}}.
- If url's origin is not the same as the service
- worker's origin associated with the payment handler, return a
- {{Promise}} resolved with null.
+ worker
's origin associated with the web-based payment handler,
+ return a {{Promise}} resolved with null.
- Let promise be a new {{Promise}}.
@@ -1210,8 +1226,8 @@
with that exception and abort these steps.
- If the origin of newContext is not the same as the
- service worker client origin associated with the payment
- handler, then:
+ service worker client origin associated with the web-based
+ payment handler, then:
- Resolve promise with null.
@@ -1271,7 +1287,7 @@
Using the simple scheme described above, a trivial HTML page that is
- loaded into the payment handler window might look like the
+ loaded into the Web-based payment handler window might look like the
following:
@@ -1350,8 +1366,8 @@
transaction and determine successful fund transfer.
- The user agent receives a successful response from the payment
- handler through resolution of the Promise provided to the
+ The user agent receives a successful response from the web-based
+ payment handler through resolution of the Promise provided to the
{{PaymentRequestEvent/respondWith}} function of the corresponding
{{PaymentRequestEvent}} interface. The application is expected to
resolve the Promise with a PaymentHandlerResponse instance
@@ -1365,8 +1381,8 @@
but are not limited to:
- - Letting the user try again, with the same payment handler or
- with a different one.
+
- Letting the user try again, with the same web-based payment
+ handler or with a different one.
- Rejecting the Promise that was created by PaymentRequest.show().
@@ -1748,39 +1764,40 @@
- The API does not share information about the user's registered
- payment handlers. Information from origins is only shared with the
- payee with the consent of the user.
+ web-based payment handlers. Information from origins is only shared
+ with the payee with the consent of the user.
- User agents should not share payment request information with any
- payment handler until the user has selected that payment handler.
+ web-based payment handler until the user has selected that payment
+ handler.
- In a browser that supports Web-based Payment Handler API, when a merchant
creates a PaymentRequest object with URL-based payment method
identifiers, a CanMakePaymentEvent will fire in registered
- payment handlers from a finite set of origins: the origins of the
- payment method manifests and their supported origins. This
- event is fired before the user has selected that payment handler,
+ web-based payment handlers from a finite set of origins: the origins
+ of the payment method manifests and their supported origins.
+ This event is fired before the user has selected that payment handler,
but it contains no information about the triggering origin (i.e.,
the merchant website) and so cannot be used to track users directly.
- We acknowledge the risk of a timing attack via
CanMakePaymentEvent:
- A merchant website sends notice via a backend channel (e.g., the
- fetch API) to a payment handler origin, sharing that they are about
- to construct a PaymentRequest object.
+ fetch API) to a web-based payment handler origin, sharing that they
+ are about to construct a PaymentRequest object.
- The merchant website then constructs the PaymentRequest,
triggering a CanMakePaymentEvent to be fired at the installed
- payment handler.
- - That payment handler contacts its own origin, and on the server
- side attempts to join the two requests.
+ web-based payment handler.
+ - That web-based payment handler contacts its own origin, and on
+ the server side attempts to join the two requests.
- User agents should allow users to disable support for the
CanMakePaymentEvent.
- In a browser that supports Web-based Payment Handler API,
- CanMakePaymentEvent will fire in registered payment handlers
- that can provide all merchant requested information including
+ CanMakePaymentEvent will fire in registered web-based payment
+ handlers that can provide all merchant requested information including
shipping address and payer's contact information whenever needed.
@@ -1791,12 +1808,12 @@
- This specification does not define how the user agent establishes
- user consent when a payment handler is first registered. The user
- agent might notify and/or prompt the user during registration.
+ user consent when a web-based payment handler is first registered. The
+ user agent might notify and/or prompt the user during registration.
- - User agents MAY reject payment handler registration for security
- reasons (e.g., due to an invalid SSL certificate) and SHOULD notify
- the user when this happens.
+
- User agents MAY reject web-based payment handler registration for
+ security reasons (e.g., due to an invalid SSL certificate) and SHOULD
+ notify the user when this happens.
@@ -1808,11 +1825,12 @@
- One goal of this specification is to minimize the user
interaction required to make a payment. However, we also want to
ensure that the user has an opportunity to consent to making a
- payment. Because payment handlers are not required to open a window
- for user interaction, user agents should take necessary steps to make
- sure the user (1) is made aware when a payment request is invoked,
- and (2) has an opportunity to interact with a payment handler before
- the merchant receives the response from that payment handler.
+ payment. Because web-based payment handlers are not required to open
+ a window for user interaction, user agents should take necessary steps
+ to make sure the user (1) is made aware when a payment request is
+ invoked, and (2) has an opportunity to interact with a web-based
+ payment handler before the merchant receives the response from that
+ payment handler.
@@ -1821,11 +1839,11 @@
User Awareness about Sharing Data Cross-Origin
- - By design, a payment handler from one origin shares data with
- another origin (e.g., the merchant site).
+
- By design, a web-based payment handler from one origin shares data
+ with another origin (e.g., the merchant site).
- To mitigate phishing attacks, it is important that user agents
- make clear to users the origin of a payment handler.
+ make clear to users the origin of a web-based payment handler.
- User agents should help users understand that they are sharing
information cross-origin, and ideally what information they are
@@ -1843,8 +1861,8 @@
considerations
- Payment method security is outside the scope of this
- specification and is addressed by payment handlers that support those
- payment methods.
+ specification and is addressed by web-based payment handlers that
+ support those payment methods.
@@ -1857,8 +1875,8 @@
apps through a payment method manifest. See the Handling a
CanMakePaymentEvent algorithm for details.
-
- The user agent is not required to make available payment handlers
- that pose security issues. Security issues might include:
+
- The user agent is not required to make available web-based payment
+ handlers that pose security issues. Security issues might include:
- Certificates that are expired, revoked, self-signed, and so
on.
@@ -1872,10 +1890,10 @@
- When a payment handler is unavailable for security reasons, the
- user agent should provide rationale to the payment handler
- developers (e.g., through console messages) and may also inform
- the user to help avoid confusion.
+ When a web-based payment handler is unavailable for security
+ reasons, the user agent should provide rationale to the web-based
+ payment handler developers (e.g., through console messages) and
+ may also inform the user to help avoid confusion.
@@ -1888,9 +1906,10 @@
-
Payment method manifests authorize origins to distribute
payment apps for a given payment method. When the user agent is
- determining whether a payment handler matches the origin listed in
- a payment method manifest, the user agent uses the scope URL
- of the payment handler's service worker registration.
+ determining whether a web-based payment handler matches the origin
+ listed in a payment method manifest, the user agent uses the
+ scope URL of the web-based payment handler's service worker
+ registration.
@@ -1914,8 +1933,8 @@
- When the Payment Request API is invoked in a "private browsing
- mode," the user agent should launch payment handlers in a private
- context. This will generally prevent sites from accessing any
+ mode," the user agent should launch web-based payment handlers in a
+ private context. This will generally prevent sites from accessing any
previously-stored information. In turn, this is likely to require
either that the user log in to the origin or re-enter payment details.
@@ -1924,8 +1943,8 @@
respondWith()
was called with `false`. We acknowledge a consequent risk: if an
entity controls both the origin of the Payment Request API call and
- the origin of the payment handler, that entity may be able to
- deduce that the user may be in private browsing mode.
+ the origin of the web-based payment handler, that entity may be able
+ to deduce that the user may be in private browsing mode.
@@ -1935,10 +1954,11 @@
Payment Handler Display Considerations
- When ordering payment handlers, the user agent is expected to honor user
- preferences over other preferences. User agents are expected to permit
- manual configuration options, such as setting a preferred payment
- handler display order for an origin, or for all origins.
+ When ordering web-based payment handlers, the user agent is expected to
+ honor user preferences over other preferences. User agents are expected
+ to permit manual configuration options, such as setting a preferred
+ web-based payment handler display order for an origin, or for all
+ origins.
User experience details are left to implementers.