Movatterモバイル変換

Handling a Payment Request

Apayment handler 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.

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

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

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

The remaining content of this section is non-normative.

A user agent may perform just-in-time installation by deriving payment handler information from thepayment method manifest that is found through theURL-based payment method identifier that the merchant requested.

Extension to the `ServiceWorkerRegistration` interface

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

ThepaymentManager attribute exposes payment handler management functionality.

PaymentManager interface

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

The {{PaymentManager}} is used bypayment handlers to manage their supported delegations.

PaymentDelegation enum

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

"shippingAddress"

The payment handler will provide shipping address whenever needed.

"payerName"

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

"payerPhone"

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

"payerEmail"

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

Extension to `ServiceWorkerGlobalScope`

        partial interface ServiceWorkerGlobalScope {          attribute EventHandler oncanmakepayment;        };

TheCanMakePaymentEvent

TheCanMakePaymentEvent is used to as a signal for whether the 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 aPaymentRequest, theuser agent MUST run the following steps:

1. Ifuser agent settings prohibit usage ofCanMakePaymentEvent (e.g., in private browsing mode), terminate these steps.
2. Letregistration be a {{ServiceWorkerRegistration}}.
3. Ifregistration is not found, terminate these steps.

4. Fire Functional Event "canmakepayment" usingCanMakePaymentEvent onregistration.

Example of handling theCanMakePaymentEvent

This example shows how to write a service worker that listens to theCanMakePaymentEvent. When aCanMakePaymentEvent is received, the service worker always returns true.

          self.addEventListener("canmakepayment", function(e) {            e.respondWith(new Promise(function(resolve, reject) {              resolve(true);            }));          });

Filtering of Payment Handlers

Given aPaymentMethodData and a payment handler that matches onpayment method identifier, this algorithm returnstrue if this payment handler can be used for payment:

1. LetmethodName be thepayment method identifier string specified in thePaymentMethodData.
2. LetmethodData be the payment method specific data ofPaymentMethodData.
3. LetpaymentHandlerOrigin be theorigin of the {{ServiceWorkerRegistration}} scope URL of the payment handler.
4. LetpaymentMethodManifest be theingested andparsedpayment method manifest for themethodName.
5. IfmethodName is aURL-based payment method identifier with the"*" stringsupported origins inpaymentMethodManifest, returntrue.
6. Otherwise, if theURL-based payment method identifiermethodName has the sameorigin aspaymentHandlerOrigin, fire theCanMakePaymentEvent in the payment handler and return the result.
7. Otherwise, ifsupported origins inpaymentMethodManifest is an ordered set of [=url/origin=] that contains thepaymentHandlerOrigin, fire theCanMakePaymentEvent in the payment handler and return the result.
8. Otherwise, return `false`.

Extension toServiceWorkerGlobalScope

This specification extends theServiceWorkerGlobalScope interface.

        partial interface ServiceWorkerGlobalScope {          attribute EventHandler onpaymentrequest;        };

ThePaymentRequestDetailsUpdate

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

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

ThePaymentRequestEvent

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 thePaymentRequest 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 aPaymentRequest by way ofPaymentRequest.show() and subsequent user selection of a payment handler, theuser agent MUST run the following steps:

1. Letregistration be the {{ServiceWorkerRegistration}} corresponding to the payment handler selected by the user.
2. Ifregistration is not found, reject the {{Promise}} that was created byPaymentRequest.show() with an {{"InvalidStateError"}} {{DOMException}} and terminate these steps.

3. Fire Functional Event "paymentrequest" using {{PaymentRequestEvent}} onregistration with the following properties:

   {{PaymentRequestEvent/topOrigin}}

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

   paymentRequestOrigin

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

   {{PaymentRequestEvent/methodData}}

   The result of executing theMethodData Population Algorithm.

   modifiers

   The result of executing theModifiers Population Algorithm.

   {{PaymentRequestEvent/total}}

   A copy of the total field on thePaymentDetailsInit from the correspondingPaymentRequest.

   paymentRequestId

   \[\[details\]\].id from thePaymentRequest.

   paymentOptions

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

   shippingOptions

   A copy of the shippingOptions field on thePaymentDetailsInit from the correspondingPaymentRequest.

   Then run the following steps in parallel, withdispatchedEvent:

   1. Wait for all of the promises in theextend lifetime promises ofdispatchedEvent to resolve.
   2. If thepayment handler has not provided aPaymentHandlerResponse, reject the {{Promise}} that was created byPaymentRequest.show() with an {{"OperationError"}} {{DOMException}}.

Open Window Algorithm

This algorithm resembles theOpen Window Algorithm 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. Letrequest be thePaymentRequest that triggered this {{PaymentRequestEvent}}.
4. Leturl be the result ofparsing theurl argument.
5. If the url parsing throws an exception, return a {{Promise}} rejected with that exception.
6. Ifurl isabout:blank, return a {{Promise}} rejected with a {{TypeError}}.
7. Ifurl's origin is not the same as theservice worker's origin associated with the payment handler, return a {{Promise}} resolved with null.
8. Letpromise be a new {{Promise}}.
9. Returnpromise and perform the remaining steps in parallel:
10. If |event|.{{ PaymentRequestEvent/[[windowClient]] }} is not null, then:
    1. If |event|.{{ PaymentRequestEvent/[[windowClient]] }}.visibilityState is not "unloaded", rejectpromise with an {{"InvalidStateError"}} {{DOMException}} and abort these steps.
11. LetnewContext be a newtop-level browsing context.
12. NavigatenewContext tourl, with exceptions enabled and replacement enabled.
13. If the navigation throws an exception, rejectpromise with that exception and abort these steps.
14. If the origin ofnewContext is not the same as the service worker client origin associated with the payment handler, then:
    1. Resolvepromise with null.
    2. Abort these steps.
15. Letclient be the result of running thecreate window client algorithm withnewContext as the argument.
16. Set |event|.{{ PaymentRequestEvent/[[windowClient]] }} toclient.
17. Resolvepromise withclient.

Example of handling the {{PaymentRequestEvent}}

This example shows how to write a service worker that listens to the {{PaymentRequestEvent}}. When a {{PaymentRequestEvent}} is received, the service worker opens a window to interact with the user.

      async function getPaymentResponseFromWindow() {        return new Promise((resolve, reject) => {          self.addEventListener("message", listener = e => {            self.removeEventListener("message", listener);            if (!e.data || !e.data.methodName) {              reject();              return;            }            resolve(e.data);          });        });      }      self.addEventListener("paymentrequest", e => {        e.respondWith((async() => {          // Open a new window for providing payment UI to user.          const windowClient = await e.openWindow("payment_ui.html");          // Send data to the opened window.          windowClient.postMessage({            total: e.total,            modifiers: e.modifiers          });          // Wait for a payment response from the opened window.          return await getPaymentResponseFromWindow();        })());      });

Using the simple scheme described above, a trivial HTML page that is loaded into thepayment handler window might look like the following:

<form><table>  <tr><th>Cardholder Name:</th><td><input name="cardholderName"></td></tr>  <tr><th>Card Number:</th><td><input name="cardNumber"></td></tr>  <tr><th>Expiration Month:</th><td><input name="expiryMonth"></td></tr>  <tr><th>Expiration Year:</th><td><input name="expiryYear"></td></tr>  <tr><th>Security Code:</th><td><input name="cardSecurityCode"></td></tr>  <tr><th></th><td><input type="submit" value="Pay"></td></tr></table></form><script>navigator.serviceWorker.addEventListener("message", e => {  /* Note: message sent from payment app is available in e.data */});document.getElementById("form").addEventListener("submit", e => {  const details = {};  ["cardholderName", "cardNumber", "expiryMonth", "expiryYear", "cardSecurityCode"]  .forEach(field => {    details[field] = form.elements[field].value;  });  const paymentAppResponse = {    methodName: "https://example.com/pay",    details  };  navigator.serviceWorker.controller.postMessage(paymentAppResponse);  window.close();});</script>

PaymentHandlerResponse 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 withmethodName andmethodDetails parameters, the user agent MUST run the following steps:

1. Run thepayment method changed algorithm withPaymentMethodChangeEvent |event| constructed using the givenmethodName andmethodDetails parameters.
2. If |event|.updateWith(detailsPromise) is not run, returnnull.
3. If |event|.updateWith(detailsPromise) throws, rethrow the error.
4. If |event|.updateWith(detailsPromise) times out (optional), throw {{"InvalidStateError"}} {{DOMException}}.
5. Construct and return aPaymentRequestDetailsUpdate from thedetailsPromise in |event|.updateWith(detailsPromise).

Change Payment Details Algorithm

When this algorithm is invoked withshippingAddress orshippingOption the user agent MUST run the following steps:

1. Run thePaymentRequest updated algorithm withPaymentRequestUpdateEvent |event| constructed using the updated details (shippingAddress orshippingOption).
2. If |event|.updateWith(detailsPromise) is not run, returnnull.
3. If |event|.updateWith(detailsPromise) throws, rethrow the error.
4. If |event|.updateWith(detailsPromise) times out (optional), throw {{"InvalidStateError"}} {{DOMException}}.
5. Construct and return aPaymentRequestDetailsUpdate from thedetailsPromise in |event|.updateWith(detailsPromise).

Respond to PaymentRequest Algorithm

When this algorithm is invoked with |event| andhandlerResponsePromise 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=] andevent's [=Event/stop immediate propagation flag=].
6. AddhandlerResponsePromise to the |event|'sextend lifetime promises
7. Increment the |event|'spending promises count by one.
8. Upon rejection ofhandlerResponsePromise:
   1. Run thepayment app failure algorithm and terminate these steps.
9. Upon fulfillment ofhandlerResponsePromise:
   1. LethandlerResponse be |value|converted to an IDL value {{PaymentHandlerResponse}}. If this throws an exception, run thepayment app failure algorithm and terminate these steps.
   2. Validate that all required members exist inhandlerResponse and are well formed.
      1. IfhandlerResponse.methodName is not present or not set to one of the values from |event|.methodData, run the payment app failure algorithm and terminate these steps.
      2. IfhandlerResponse.details is not present or notJSON-serializable, run thepayment app failure algorithm and terminate these steps.
      3. LetshippingRequired be therequestShipping value of the associated PaymentRequest'spaymentOptions. IfshippingRequired andhandlerResponse.shippingAddress is not present, run thepayment app failure algorithm and terminate these steps.
      4. IfshippingRequired andhandlerResponse.shippingOption is not present or not set to one of shipping options identifiers from |event|.shippingOptions, run thepayment app failure algorithm and terminate these steps.
      5. LetpayerNameRequired be therequestPayerName value of the associated PaymentRequest'spaymentOptions. IfpayerNameRequired andhandlerResponse.payerName is not present, run thepayment app failure algorithm and terminate these steps.
      6. LetpayerEmailRequired be therequestPayerEmail value of the associated PaymentRequest'spaymentOptions. IfpayerEmailRequired andhandlerResponse.payerEmail is not present, run thepayment app failure algorithm and terminate these steps.
      7. LetpayerPhoneRequired be therequestPayerPhone value of the associated PaymentRequest'spaymentOptions. IfpayerPhoneRequired andhandlerResponse.payerPhone is not present, run thepayment app failure algorithm and terminate these steps.
   3. Serialize required members ofhandlerResponse (methodName anddetails are always required;shippingAddress andshippingOption are required whenshippingRequired is true;payerName,payerEmail, andpayerPhone are required whenpayerNameRequired,payerEmailRequired, andpayerPhoneRequired are true, respectively.):
      1. For eachmemberinhandlerResponseLetserializeMemberbe the result ofStructuredSerializewith handlerResponse.member. Rethrow any exceptions.
   4. The user agent MUST run theuser accepts the payment request algorithm as defined in [[!payment-request]], replacing steps 9-15 with these steps or their equivalent.
      1. Deserialize serialized members:
         1. For eachserializeMemberletmemberbe the result ofStructuredDeserializewithserializeMember. Rethrow any exceptions.
      2. If any exception occurs in the above step, then run thepayment app failure algorithm and terminate these steps.
      3. AssignmethodName to associated PaymentRequest'sresponse.methodName.
      4. Assigndetails to associated PaymentReqeust'sresponse.details.
      5. IfshippingRequired, then set the shippingAddress attribute of associated PaymentReqeust'sresponse toshippingAddress. Otherwise, set it to null.
      6. IfshippingRequired, then set the shippingOption attribute of associated PaymentReqeust'sresponse toshippingOption. Otherwise, set it to null.
      7. IfpayerNameRequired, then set the payerName attribute of associated PaymentReqeust'sresponse topayerName. Otherwise, set it to null.
      8. IfpayerEmailRequired, then set thepayerEmail attribute of associated PaymentReqeust'sresponse topayerEmail. Otherwise, set it to null.
      9. IfpayerPhoneRequired, then set thepayerPhone attribute of associated PaymentReqeust'sresponse topayerPhone. Otherwise, set it to null.
10. Upon fulfillment orupon rejection ofhandlerResponsePromise,queue a microtask to perform the following steps:
    1. Decrement the |event|'spending promises count by one.
    2. Letregistration be thethis'srelevant global object's associatedservice worker'scontaining service worker registration.
    3. Ifregistration is not null, invokeTry Activate withregistration.

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 anID that parties in the ecosystem (including payment app providers and payees) can use for reconciliation after network or other failures.

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; seeissue 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 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.
• In a browser that supports Payment Handler API, when a merchant creates a PaymentRequest object with URL-based payment method identifiers, aCanMakePaymentEvent will fire in registered payment handlers from a finite set of origins: the origins of the payment method manifests and theirsupported 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 viaCanMakePaymentEvent:
  • 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.
  • The merchant website then constructs the PaymentRequest, triggering aCanMakePaymentEvent 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.
• User agents should allow users to disable support for theCanMakePaymentEvent.
• In a browser that supports Payment Handler API,CanMakePaymentEvent will fire in registered 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 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 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 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.

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).
• To mitigate phishing attacks, it is important that user agents make clear to users the origin of a payment handler.
• User agents should help users understand that they are sharing information cross-origin, and ideally what information they are sharing.

Secure Communications

• SeeService Worker security considerations
• Payment method security is outside the scope of this specification and is addressed by payment handlers that support those payment methods.

Authorized Payment Apps

• The party responsible for a payment method authorizes payment apps through apayment method manifest. See theHandling a CanMakePaymentEvent algorithm for details.
• The user agent is not required to make available 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 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.

Supported Origin

• 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 apayment method manifest, the user agent uses the scope URL of the payment handler'sservice worker registration.

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 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.
• TheCanMakePaymentEvent event should not be fired in private browsing mode. The user agent should behave as ifrespondWith() 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.