Handling a Payment Request

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 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 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 the user through a new window or other APIs (such as [[[WebCryptoAPI]]]) or with other services and origins through web requests or other means.

This specification does not address these activities that occur 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:

• how the user establishes an account with an origin that provides payment services.
• how an origin authenticates a user.
• how communication takes place between the payee server and the payee Web application, or between a payment app origin and other parties.

Thus, an origin will rely on many other Web technologies defined elsewhere for lifecycle management, security, user authentication, user interaction, and so on.

Relation to Other Types of Payment Apps

This specification does not address how third-party mobile payment apps interact (through proprietary mechanisms) with user agents, or how user agents themselves provide simple payment app functionality.

Just-in-time registration

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 web-based payment handler information from the that is found through the that the merchant requested.

Extension to the `ServiceWorkerRegistration` interface

 partial interface ServiceWorkerRegistration {
 [SameObject] readonly attribute PaymentManager paymentManager;
 };
 

The paymentManager attribute exposes web-based payment handler management functionality.

PaymentManager interface

 [SecureContext, Exposed=(Window)]
 interface PaymentManager {
 attribute DOMString userHint;
 Promise<undefined> enableDelegations(sequence<PaymentDelegation> delegations);
 };
 

The {{PaymentManager}} is used by s to manage their supported delegations.

PaymentDelegation enum

 enum PaymentDelegation {
 "shippingAddress",
 "payerName",
 "payerPhone",
 "payerEmail"
 };
 

"shippingAddress"

The web-based payment handler will provide shipping address whenever needed.

"payerName"

The web-based payment handler will provide payer's name whenever needed.

"payerPhone"

The web-based payment handler will provide payer's phone whenever needed.

"payerEmail"

The web-based payment handler will provide payer's email whenever needed.

Extension to `ServiceWorkerGlobalScope`

 partial interface ServiceWorkerGlobalScope {
 attribute EventHandler oncanmakepayment;
 };
 

The CanMakePaymentEvent

The is used to as a signal for whether the web-based payment handler is able to respond to a payment request.

 [Exposed=ServiceWorker]
 interface CanMakePaymentEvent : ExtendableEvent {
 constructor(DOMString type);
 undefined respondWith(Promise<boolean> canMakePaymentResponse);
 };
 

Handling a CanMakePaymentEvent

Upon receiving a , the MUST run the following steps:

1. If settings prohibit usage of (e.g., in private browsing mode), terminate these steps.
2. Let registration be a {{ServiceWorkerRegistration}}.
3. If registration is not found, terminate these steps.

4. "canmakepayment" using on registration.

Filtering of Payment Handlers

Given a and a web-based payment handler that matches on , this algorithm returns true if this web-based payment handler can be used for payment:

1. Let methodName be the string specified in the .
2. Let methodData be the payment method specific data of .
3. Let paymentHandlerOrigin be the of the {{ServiceWorkerRegistration}} scope URL of the web-based payment handler.
4. Let paymentMethodManifest be the and for the methodName.
5. If methodName is a with the "*" string in paymentMethodManifest, return true.
6. Otherwise, if the methodName has the same as paymentHandlerOrigin, fire the in the web-based payment handler and return the result.
7. Otherwise, if in paymentMethodManifest is an ordered set of [=url/origin=] that contains the paymentHandlerOrigin, fire the in the web-based payment handler and return the result.
8. Otherwise, return `false`.

Extension to

This specification extends the interface.

 partial interface ServiceWorkerGlobalScope {
 attribute EventHandler onpaymentrequest;
 };
 

The PaymentRequestDetailsUpdate

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 web-based payment handler.

 dictionary PaymentRequestDetailsUpdate {
 DOMString error;
 PaymentCurrencyAmount total;
 sequence<PaymentDetailsModifier> modifiers;
 sequence<PaymentShippingOption> shippingOptions;
 object paymentMethodErrors;
 AddressErrors shippingAddressErrors;
 };
 

The PaymentRequestEvent

The PaymentRequestEvent represents the data and methods available to a Payment Handler after selection by the user. The user agent communicates a subset of data available from the to the Payment Handler.

 [Exposed=ServiceWorker]
 interface PaymentRequestEvent : ExtendableEvent {
 constructor(DOMString type, optional PaymentRequestEventInit eventInitDict = {});
 readonly attribute USVString topOrigin;
 readonly attribute USVString paymentRequestOrigin;
 readonly attribute DOMString paymentRequestId;
 readonly attribute FrozenArray<PaymentMethodData> methodData;
 readonly attribute object total;
 readonly attribute FrozenArray<PaymentDetailsModifier> modifiers;
 readonly attribute object? paymentOptions;
 readonly attribute FrozenArray<PaymentShippingOption>? shippingOptions;
 Promise<WindowClient?> openWindow(USVString url);
 Promise<PaymentRequestDetailsUpdate?> changePaymentMethod(DOMString methodName, optional object? methodDetails = null);
 Promise<PaymentRequestDetailsUpdate?> changeShippingAddress(optional AddressInit shippingAddress = {});
 Promise<PaymentRequestDetailsUpdate?> changeShippingOption(DOMString shippingOption);
 undefined respondWith(Promise<PaymentHandlerResponse> handlerResponsePromise);
 };
 

Should payment apps receive user data stored in the user agent upon explicit consent from the user? The payment app could request permission either at installation or when the payment app is first invoked.

 dictionary PaymentRequestEventInit : ExtendableEventInit {
 USVString topOrigin;
 USVString paymentRequestOrigin;
 DOMString paymentRequestId;
 sequence<PaymentMethodData> methodData;
 PaymentCurrencyAmount total;
 sequence<PaymentDetailsModifier> modifiers;
 PaymentOptions paymentOptions;
 sequence<PaymentShippingOption> shippingOptions;
 };
 

Internal Slots

Instances of {{PaymentRequestEvent}} are created with the internal slots in the following table:

Handling a PaymentRequestEvent

Upon receiving a by way of and subsequent user selection of a web-based payment handler, the MUST run the following steps:

1. Let registration be the {{ServiceWorkerRegistration}} corresponding to the web-based payment handler selected by the user.
2. If registration is not found, reject the {{Promise}} that was created by with an {{"InvalidStateError"}} {{DOMException}} and terminate these steps.

3. "paymentrequest" using {{PaymentRequestEvent}} on registration with the following properties:

   {{PaymentRequestEvent/topOrigin}}

   the [=serialization of an origin=] of the top level payee web page.

   the [=serialization of an origin=] of the context where PaymentRequest was initialized.

   {{PaymentRequestEvent/methodData}}

   The result of executing the .

   The result of executing the .

   {{PaymentRequestEvent/total}}

   A copy of the total field on the from the corresponding .

   \[\[details\]\]. from the .

   A copy of the paymentOptions dictionary passed to the constructor of the corresponding .

   A copy of the shippingOptions field on the from the corresponding .

   Then run the following steps in parallel, with dispatchedEvent:

   1. Wait for all of the promises in the of dispatchedEvent to resolve.
   2. If the has not provided a , reject the {{Promise}} that was created by with an {{"OperationError"}} {{DOMException}}.

Open Window Algorithm

This algorithm resembles the in the Service Workers specification.

Should we refer to the Service Workers specification instead of copying their steps?

1. Let |event| be this {{PaymentRequestEvent}}.
2. If |event|'s {{Event/isTrusted}} attribute is false, return a {{Promise}} rejected with a {{"InvalidStateError"}} {{DOMException}}.
3. Let request be the that triggered this {{PaymentRequestEvent}}.
4. Let url be the result of the url argument.
5. If the url parsing throws an exception, return a {{Promise}} rejected with that exception.
6. If url is about:blank, return a {{Promise}} rejected with a {{TypeError}}.
7. If url's origin is not the same as the 's origin associated with the web-based payment handler, return a {{Promise}} resolved with null.
8. Let promise be a new {{Promise}}.
9. Return promise and perform the remaining steps in parallel:
10. If |event|.{{ PaymentRequestEvent/[[windowClient]] }} is not null, then:
    1. If |event|.{{ PaymentRequestEvent/[[windowClient]] }}. is not "unloaded", reject promise with an {{"InvalidStateError"}} {{DOMException}} and abort these steps.
11. Let newContext be a new .
12. newContext to url, with exceptions enabled and replacement enabled.
13. If the navigation throws an exception, reject promise with that exception and abort these steps.
14. If the origin of newContext is not the same as the origin associated with the web-based payment handler, then:
    1. Resolve promise with null.
    2. Abort these steps.
15. Let client be the result of running the algorithm with newContext as the argument.
16. Set |event|.{{ PaymentRequestEvent/[[windowClient]] }} to client.
17. Resolve promise with client.

PaymentHandlerResponse dictionary

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 instance containing the payment response. In case of user cancellation or error, the application may signal failure by rejecting the Promise.

The PaymentHandlerResponse is conveyed using the following dictionary:

 dictionary PaymentHandlerResponse {
 DOMString methodName;
 object details;
 DOMString? payerName;
 DOMString? payerEmail;
 DOMString? payerPhone;
 AddressInit shippingAddress;
 DOMString? shippingOption;
 };
 

Change Payment Method Algorithm

When this algorithm is invoked with methodName and methodDetails parameters, the user agent MUST run the following steps:

1. Run the with |event| constructed using the given methodName and methodDetails parameters.
2. If |event|. is not run, return null.
3. If |event|. throws, rethrow the error.
4. If |event|. times out (optional), throw {{"InvalidStateError"}} {{DOMException}}.
5. Construct and return a from the detailsPromise in |event|..

Change Payment Details Algorithm

When this algorithm is invoked with shippingAddress or shippingOption the user agent MUST run the following steps:

1. Run the with |event| constructed using the updated details (shippingAddress or shippingOption).
2. If |event|. is not run, return null.
3. If |event|. throws, rethrow the error.
4. If |event|. times out (optional), throw {{"InvalidStateError"}} {{DOMException}}.
5. Construct and return a from the detailsPromise in |event|..

Respond to PaymentRequest Algorithm

When this algorithm is invoked with |event| and handlerResponsePromise parameters, the user agent MUST run the following steps:

1. If |event|'s {{Event/isTrusted}} is false, then throw an "InvalidStateError" {{DOMException}} and abort these steps.
2. If |event|'s [=Event/dispatch flag=] is unset, then throw an {{"InvalidStateError"}} {{DOMException}} and abort these steps.
3. If |event|.{{ PaymentRequestEvent/[[respondWithCalled]] }} is true, throw an {{"InvalidStateError"}} {{DOMException}} and abort these steps.
4. Set |event|.{{ PaymentRequestEvent/[[respondWithCalled]] }} to true.
5. Set the |event|'s [=Event/stop propagation flag=] and event's [=Event/stop immediate propagation flag=].
6. Add handlerResponsePromise to the |event|'s
7. Increment the |event|'s by one.
8. of handlerResponsePromise with |reason|:
   1. Run the with |reason|, and terminate these steps.
9. of handlerResponsePromise:
   1. Let handlerResponse be |value| {{PaymentHandlerResponse}}. If this throws an exception, run the with an {{"OperationError"}} {{DOMException}}, and terminate these steps.
   2. Validate that all required members exist in handlerResponse and are well formed.
      1. If handlerResponse. is not present or not set to one of the values from |event|., run the with an {{"OperationError"}} {{DOMException}}, and terminate these steps.
      2. If handlerResponse. is not present or not , run the with an {{"OperationError"}} {{DOMException}}, and terminate these steps.
      3. Let shippingRequired be the value of the associated PaymentRequest's . If shippingRequired and handlerResponse. is not present, run the with an {{"OperationError"}} {{DOMException}}, and terminate these steps.
      4. If shippingRequired and handlerResponse. is not present or not set to one of shipping options identifiers from |event|., run the with an {{"OperationError"}} {{DOMException}}, and terminate these steps.
      5. Let payerNameRequired be the value of the associated PaymentRequest's . If payerNameRequired and handlerResponse. is not present, run the with an {{"OperationError"}} {{DOMException}}, and terminate these steps.
      6. Let payerEmailRequired be the value of the associated PaymentRequest's . If payerEmailRequired and handlerResponse. is not present, run the with an {{"OperationError"}} {{DOMException}}, and terminate these steps.
      7. Let payerPhoneRequired be the value of the associated PaymentRequest's . If payerPhoneRequired and handlerResponse. is not present, run the with an {{"OperationError"}} {{DOMException}}, and terminate these steps.
   3. Serialize required members of handlerResponse ( methodName and details are always required; shippingAddress and shippingOption are required when shippingRequired is true; payerName, payerEmail, and payerPhone are required when payerNameRequired, payerEmailRequired, and payerPhoneRequired are true, respectively.):
      1. For each memberin handlerResponseLet serializeMemberbe the result of with handlerResponse.member. Rethrow any exceptions.
   4. The user agent MUST run the as defined in [[!payment-request]], replacing steps 9-15 with these steps or their equivalent.
      1. Deserialize serialized members:
         1. For each serializeMemberlet memberbe the result of with serializeMember. Rethrow any exceptions.
      2. If any exception occurs in the above step, then run the with an {{"OperationError"}} {{DOMException}}, and terminate these steps.
      3. Assign methodName to associated PaymentRequest's ..
      4. Assign details to associated PaymentReqeust's ..
      5. If shippingRequired, then set the attribute of associated PaymentReqeust's to shippingAddress. Otherwise, set it to null.
      6. If shippingRequired, then set the attribute of associated PaymentReqeust's to shippingOption. Otherwise, set it to null.
      7. If payerNameRequired, then set the attribute of associated PaymentReqeust's to payerName. Otherwise, set it to null.
      8. If payerEmailRequired, then set the attribute of associated PaymentReqeust's to payerEmail. Otherwise, set it to null.
      9. If payerPhoneRequired, then set the attribute of associated PaymentReqeust's to payerPhone. Otherwise, set it to null.
10. or of handlerResponsePromise, to perform the following steps:
    1. Decrement the |event|'s by one.
    2. Let registration be the 's 's associated 's .
    3. If registration is not null, invoke with registration.

The following example shows how to respond to a payment request:

 paymentRequestEvent.respondWith(new Promise(function(accept,reject) {
 /* ... processing may occur here ... */
 accept({
 methodName: "https://example.com/pay",
 details: {
 cardHolderName: "John Smith",
 cardNumber: "1232343451234",
 expiryMonth: "12",
 expiryYear : "2020",
 cardSecurityCode: "123"
 },
 shippingAddress: {
 addressLine: [
 "1875 Explorer St #1000",
 ],
 city: "Reston",
 country: "US",
 dependentLocality: "",
 organization: "",
 phone: "+15555555555",
 postalCode: "20190",
 recipient: "John Smith",
 region: "VA",
 sortingCode: ""
 },
 shippingOption: "express",
 payerEmail: "john.smith@gmail.com",
 });
 }));
 

[[!payment-request]] defines an that parties in the ecosystem (including payment app providers and payees) can use for reconciliation after network or other failures.

Payment App Failure Algorithm

When this algorithm is invoked with |reason|, the user agent MUST run the following steps:

1. If |reason| is an {{"OperationError"}} {{DOMException}}, then run the as defined in [[!payment-request]].
2. Otherwise, run the as defined in [[!payment-request]].

   Previous versions of this specification did not define what happened when the was invoked. In practice, implementors acted as if the was run. To maintain as much backwards compatibility as possible, while still introducing a way for web-based payment handlers to indicate internal error, this specification now maps all reason values other than a {{"OperationError"}} {{DOMException}} to user abort. Future versions of this specification may add additional handled values.

Addresses

The Web Payments Working Group removed support for shipping and billing addresses from the original version of Payment Request API due to privacy issues; see issue 842. In order to provide documentation for implementations that continue to support this capability, the Working Group is now restoring the feature with an expectation of addressing privacy issues. In doing so the Working Group may also make changes to Payment Request API based on the evolution of other APIs (e.g., the Content Picker API).

Information about the User Environment

• The API does not share information about the user's registered 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 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 will fire in registered web-based payment handlers from a finite set of origins: the origins of the payment method manifests and their . 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 :
  • A merchant website sends notice via a backend channel (e.g., the 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 to be fired at the installed 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 .
• In a browser that supports Web-based Payment Handler API, 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.

User Consent to Install a Payment Handler

• This specification does not define how the user agent establishes 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 web-based payment handler registration for security reasons (e.g., due to an invalid SSL certificate) and SHOULD notify the user when this happens.

User Consent before Payment

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

User Awareness about Sharing Data Cross-Origin

• 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 web-based payment handler.
• User agents should help users understand that they are sharing information cross-origin, and ideally what information they are sharing.

Secure Communications

• See
• Payment method security is outside the scope of this specification and is addressed by web-based payment handlers that support those payment methods.

Authorized Payment Apps

• The party responsible for a payment method authorizes payment apps through a . See the algorithm for details.
• 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.
  • Mixed content
  • Page available through HTTPs redirects to one that is not.
  • Payment handler is known from safe browsing database to be malicious

  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.

Supported Origin

• authorize origins to distribute payment apps for a given payment method. When the user agent is determining whether a web-based payment handler matches the origin listed in a , the user agent uses the scope URL of the web-based payment handler's .

Data Validation

• To mitigate the scenario where a hijacked payee site submits fraudlent or malformed payment method data (or, for that matter, payment request data) to the payee's server, the payee's server should validate the data format and correlate the data with authoritative information on the server such as accepted payment methods, total, display items, and shipping address.

Private Browsing Mode

• When the Payment Request API is invoked in a "private browsing 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.
• The event should not be fired in private browsing mode. The user agent should behave as if 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 web-based payment handler, that entity may be able to deduce that the user may be in private browsing mode.