Payment Handler API

If a payment handler is not registered when a merchant invokes 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 the payment method manifest that is found through the URL-based payment method identifier that the merchant requested.

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

The paymentManager attribute exposes payment handler management functionality.

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

The PaymentManager is used by payment handlers to manage their supported delegations.

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

WebIDLpartial interface ServiceWorkerGlobalScope {
  attribute EventHandler oncanmakepayment;
};

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

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

Upon receiving a PaymentRequest, the user agent MUST run the following steps:

1. If user agent settings prohibit usage of CanMakePaymentEvent (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. Fire Functional Event "canmakepayment" using CanMakePaymentEvent on registration.

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:

1. Let methodName be the payment method identifier string specified in the PaymentMethodData.
2. Let methodData be the payment method specific data of PaymentMethodData.
3. Let paymentHandlerOrigin be the origin of the ServiceWorkerRegistration scope URL of the payment handler.
4. Let paymentMethodManifest be the ingested and parsed payment method manifest for the methodName.
5. If methodName is a URL-based payment method identifier with the "*" string supported origins in paymentMethodManifest, return true.
6. 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.
7. Otherwise, if supported origins in paymentMethodManifest is an ordered set of origin that contains the paymentHandlerOrigin, fire the CanMakePaymentEvent in the payment handler and return the result.
8. Otherwise, return false.

This specification extends the ServiceWorkerGlobalScope interface.

WebIDLpartial interface ServiceWorkerGlobalScope {
  attribute EventHandler onpaymentrequest;
};

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.

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

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 PaymentRequest to the Payment Handler.

WebIDL[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);
};

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

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

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:

1. Let registration be the ServiceWorkerRegistration corresponding to the payment handler selected by the user.
2. If registration is not found, reject the Promise that was created by PaymentRequest.show() with an "InvalidStateError" DOMException and terminate these steps.

3. Fire Functional Event "paymentrequest" using PaymentRequestEvent on registration with the following properties:

   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.

   methodData

   The result of executing the MethodData Population Algorithm.

   modifiers

   The result of executing the Modifiers Population Algorithm.

   total

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

   paymentRequestId

   \[\[details\]\].id from the PaymentRequest.

   paymentOptions

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

   shippingOptions

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

   Then run the following steps in parallel, with dispatchedEvent:

   1. Wait for all of the promises in the extend lifetime promises of dispatchedEvent to resolve.
   2. If the payment handler has not provided a PaymentHandlerResponse, reject the Promise that was created by PaymentRequest.show() with an "OperationError" DOMException.

1. Let event be this PaymentRequestEvent.
2. If event's isTrusted attribute is false, return a Promise rejected with a "InvalidStateError" DOMException.
3. Let request be the PaymentRequest that triggered this PaymentRequestEvent.
4. Let url be the result of parsing 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 service worker's origin associated with the 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.[[windowClient]] is not null, then:
    1. If event.[[windowClient]].visibilityState is not "unloaded", reject promise with an "InvalidStateError" DOMException and abort these steps.
11. Let newContext be a new top-level browsing context.
12. Navigate 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 service worker client origin associated with the payment handler, then:
    1. Resolve promise with null.
    2. Abort these steps.
15. Let client be the result of running the create window client algorithm with newContext as the argument.
16. Set event.[[windowClient]] to client.
17. Resolve promise with client.

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

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

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

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

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

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

1. If event's isTrusted is false, then throw an "InvalidStateError" DOMException and abort these steps.
2. If event's dispatch flag is unset, then throw an "InvalidStateError" DOMException and abort these steps.
3. If event.[[respondWithCalled]] is true, throw an "InvalidStateError" DOMException and abort these steps.
4. Set event.[[respondWithCalled]] to true.
5. Set the event's stop propagation flag and event's stop immediate propagation flag.
6. Add handlerResponsePromise to the event's extend lifetime promises
7. Increment the event's pending promises count by one.
8. Upon rejection of handlerResponsePromise:
   1. Run the payment app failure algorithm and terminate these steps.
9. Upon fulfillment of handlerResponsePromise:
   1. Let handlerResponse be value converted to an IDL value PaymentHandlerResponse. If this throws an exception, run the payment app failure algorithm and terminate these steps.
   2. Validate that all required members exist in handlerResponse and are well formed.
      1. If handlerResponse.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. If handlerResponse.details is not present or not JSON-serializable, run the payment app failure algorithm and terminate these steps.
      3. Let shippingRequired be the requestShipping value of the associated PaymentRequest's paymentOptions. If shippingRequired and handlerResponse.shippingAddress is not present, run the payment app failure algorithm and terminate these steps.
      4. If shippingRequired and handlerResponse.shippingOption is not present or not set to one of shipping options identifiers from event.shippingOptions, run the payment app failure algorithm and terminate these steps.
      5. Let payerNameRequired be the requestPayerName value of the associated PaymentRequest's paymentOptions. If payerNameRequired and handlerResponse.payerName is not present, run the payment app failure algorithm and terminate these steps.
      6. Let payerEmailRequired be the requestPayerEmail value of the associated PaymentRequest's paymentOptions. If payerEmailRequired and handlerResponse.payerEmail is not present, run the payment app failure algorithm and terminate these steps.
      7. Let payerPhoneRequired be the requestPayerPhone value of the associated PaymentRequest's paymentOptions. If payerPhoneRequired and handlerResponse.payerPhone is not present, run the payment app failure algorithm 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 StructuredSerializewith handlerResponse.member. Rethrow any exceptions.
   4. The user agent MUST run the user 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 each serializeMemberlet memberbe the result of StructuredDeserializewith serializeMember. Rethrow any exceptions.
      2. If any exception occurs in the above step, then run the payment app failure algorithm and terminate these steps.
      3. Assign methodName to associated PaymentRequest's response.methodName.
      4. Assign details to associated PaymentReqeust's response.details.
      5. If shippingRequired, then set the shippingAddress attribute of associated PaymentReqeust's response to shippingAddress. Otherwise, set it to null.
      6. If shippingRequired, then set the shippingOption attribute of associated PaymentReqeust's response to shippingOption. Otherwise, set it to null.
      7. If payerNameRequired, then set the payerName attribute of associated PaymentReqeust's response to payerName. Otherwise, set it to null.
      8. If payerEmailRequired, then set the payerEmail attribute of associated PaymentReqeust's response to payerEmail. Otherwise, set it to null.
      9. If payerPhoneRequired, then set the payerPhone attribute of associated PaymentReqeust's response to payerPhone. Otherwise, set it to null.
10. Upon fulfillment or upon rejection of handlerResponsePromise, queue a microtask to perform the following steps:
    1. Decrement the event's pending promises count by one.
    2. Let registration be the this's relevant global object's associated service worker's containing service worker registration.
    3. If registration is not null, invoke Try Activate 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",
  });
}));

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

• 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, 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, 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.
  • 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.
• User agents should allow users to disable support for the CanMakePaymentEvent.
• 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.

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

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

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

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

• The party responsible for a payment method authorizes payment 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:
  • 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.

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

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

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