Payment Handler API

3.2.1 instruments attribute

This attribute allows manipulation of payment instruments associated with a service worker (and therefore its payment handler). To be a candidate payment handler, a handler must have at least one registered payment instrument to present to the user. That instrument needs to match the payment methods and required capabilities specified by the payment request.

3.2.2 requestPermission() method

When called, this method executes the following steps:

1. Let p be a new promise.
2. Return p and perform the remaining steps in parallel:
3. Let permission be the result of running retrieve the permission state algorithm of the permission associated with payment handler 's origin .
4. If permission is "prompt", ask the user whether allowing adding new payment instruments for the current settings object 's origin is acceptable. If it is, set permission to "granted", and "denied" otherwise.
5. Resolve p with permission .

3.2.3 userHint attribute

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 a agent displays all payment instruments available through a payment handler, it may cause confusion to display the additional hint.

3.3.1 delete() method

When called, this method executes the following steps:

1. Let p be a new promise.
2. Return p and perform the remaining steps in parallel:
3. If the collection contains a PaymentInstrument with a matching instrumentKey , remove it from the collection and resolve p with true .
4. Otherwise, resolve p with false .

3.3.2 get() method

When called, this method executes the following steps:

1. Let p be a new promise.
2. Return p and perform the remaining steps in parallel:
3. If the collection contains a PaymentInstrument with a matching instrumentKey , resolve p with that PaymentInstrument .
4. Otherwise, resolve p with undefined .

3.3.3 keys() method

When called, this method executes the following steps:

1. Let p be a new promise.
2. Return p and perform the remaining steps in parallel:
3. Resolve p with a Sequence that contains all the instrumentKey s for the PaymentInstrument s contained in the collection, in original insertion order.

3.3.4 has() method

When called, this method executes the following steps:

1. Let p be a new promise.
2. Return p and perform the remaining steps in parallel:
3. If the collection contains a PaymentInstrument with a matching instrumentKey , resolve p with true .
4. Otherwise, resolve p with false .

3.3.5 set() method

When called, this method executes the following steps:

1. Let permission be the result of running retrieving the permission state of the permission associated with payment handler 's origin .
2. If permission is not "granted", then return a Promise rejected with a " NotAllowedError " DOMException .
3. If the icons member of details is present, then:
   1. Let convertedIcons be the result of running the convert image objects algorithm passing details . icons as the argument.
   2. If the convertedIcons is an empty Sequence , then return a Promise rejected with a TypeError .
   3. Set details . icons to convertedIcons .
4. Let p be a new promise.
5. Return p and perform the remaining steps in parallel:
6. If the icons member of details is present, then for each icon in details . icons :
   1. If the user agent wants to display the icon , then:
      1. Let fetchedImage be the result of running the fetching image object passing icon as the argument.
      2. Set icon . [[fetchedImage]] to fetchedImage .
7. If the collection contains a PaymentInstrument with a matching instrumentKey , replace it with the PaymentInstrument in details .
8. Otherwise, insert the PaymentInstrument in details as a new member of the collection and associate it with the key instrumentKey .
9. Resolve p .

3.3.6 clear() method

When called, this method executes the following steps:

1. Let p be a new promise.
2. Return p and perform the remaining steps in parallel:
3. Remove all PaymentInstrument s from the collection and resolve p .

3.3.7 PaymentInstrument dictionary

dictionary PaymentInstrument {
    required DOMString             name;
             sequence<ImageObject> icons;
             DOMString             method;
             object                capabilities;
};

name member

The name member is a string that represents the label for this PaymentInstrument as it is usually displayed to the user.

icons member

The icons member is an array of image objects that can serve as iconic representations of the payment instrument when presented to the user for selection.

method member

The method member is the payment method identifier of the payment method supported by this instrument.

capabilities member

The capabilities member is a list of payment-method-specific capabilities that this payment handler is capable of supporting for this instrument. For example, for the basic-card payment method, this object will consist of an object with two fields: one for supportedNetworks , and another for supportedTypes .

3.3.8 ImageObject dictionary

dictionary ImageObject {
    required USVString src;
             DOMString sizes;
             DOMString type;
};

src member

The src member is used to specify the ImageObject 's source. It is a URL from which the user agent can fetch the image’s data.

sizes member

The sizes member is used to specify the ImageObject 's sizes. It follows the spec of sizes member in HTML link element , which is a string consisting of an unordered set of unique space-separated tokens which are ASCII case-insensitive that represents the dimensions of an image. Each keyword is either an ASCII case-insensitive match for the string "any", or a value that consists of two valid non-negative integers that do not have a leading U+0030 DIGIT ZERO (0) character and that are separated by a single U+0078 LATIN SMALL LETTER X or U+0058 LATIN CAPITAL LETTER X character. The keywords represent icon sizes in raw pixels (as opposed to CSS pixels). When multiple image objects are available, a user agent MAY use the value to decide which icon is most suitable for a display context (and ignore any that are inappropriate). The parsing steps for the sizes member MUST follow the parsing steps for HTML link element sizes attribute .

type member

The type member is used to specify the ImageObject 's MIME type. It is a hint as to the media type of the image. The purpose of this member is to allow a user agent to ignore images of media types it does not support.

3.3.9 Convert image objects

When this algorithm with inputImages parameter is invoked, the user agent must run the following steps:

1. Let outputImages be an empty Sequence of ImageObject .
2. For each image in inputImages :
   1. If image . type is not a valid MIME type or the value of type is not a supported media format, then return an empty Sequence of ImageObject .
   2. If image . sizes is not a valid value , then return an empty Sequence of ImageObject .
   3. Let url be the result of parsing image . src with the context object 's relevant settings object 's API base URL .
   4. If url is failure, then return an empty Sequence of ImageObject .
   5. If url 's scheme is not "https", then return an empty Sequence of ImageObject .
   6. Set image . src to url .
   7. Append image to outputImages
3. Return outputImages .

According to the step 2.3, it is also possible to use the relative url for image . src . The following examples illustrate how relative URL resolution works in different execution contexts.

<-- In this example, code is located in https://www.example.com/bobpay/index.html -->
<script>
const instrumentKey = "c8126178-3bba-4d09-8f00-0771bcfd3b11";
const registration = await navigator.serviceWorker.register("/register/sw.js");
await registration.paymentManager.paymentInstruments.set({
  instrumentKey,
  {
    name: "My Bob Pay Account: john@example.com",
    method: "https://bobpay.com",
    icons: [{
      src: "icon/lowres.webp",
      sizes: "48x48",
      type: "image/webp"
    }]
  });
const { storedInstrument } =
  await registration.paymentManager.paymentInstruments.get(instrumentKey);
// storedInstrument.icons[0].src == "https://www.example.com/bobpay/icon/lowres.webp";
</script>

// In this example, code is located in https://www.example.com/register/sw.js
const instrumentKey = "c8126178-3bba-4d09-8f00-0771bcfd3b11";
await self.registration.paymentManager.paymentInstruments.set({
  instrumentKey,
  {
    name: "My Bob Pay Account: john@example.com",
    method: "https://bobpay.com",
    icons: [{
      src: "../bobpay/icon/lowres.webp",
      sizes: "48x48",
      type: "image/webp"
    }]
  });
const { storedInstrument } =
  await registration.paymentManager.paymentInstruments.get(instrumentKey);
// storedInstrument.icons[0].src == "https://www.example.com/bobpay/icon/lowres.webp";

4.1.1 oncanmakepayment attribute

The oncanmakepayment attribute is an event handler whose corresponding event handler event type is canmakepayment.

4.2.1 respondWith() method

This method is used by the payment handler to indicate whether it can respond to a payment request. The respondWith(canMakePaymentPromise) method MUST act as follows:

1. Let event be this CanMakePaymentEvent instance.
2. If event 's isTrusted attribute is false, then throw an " InvalidStateError " DOMException .
3. If event 's dispatch flag is unset, then throw an " InvalidStateError " DOMException .
4. If event . [[resultPromise]] is not null, throw an " InvalidStateError " DOMException .
5. Set event . [[resultPromise]] to PaymentRequest 's canMakePaymentPromise .
6. Set the event 's stop propagation flag and event 's stop immediate propagation flag .
7. Add canMakePaymentPromise to the event 's extend lifetime promises .
8. Increment the event 's pending promises count by one.
9. Upon fulfillment or rejection of canMakePaymentPromise , queue a microtask to perform the following steps:
   1. Decrement the event 's pending promises count by one.
   2. Let registration be the context object 's relevant global object 's associated service worker 's containing service worker registration .
   3. If registration ’s uninstalling flag is set, invoke Try Clear Registration with registration .
   4. If registration is not null, invoke Try Activate with registration .
10. Upon fulfillment of canMakePaymentPromise with value value ,
    1. Resolve the pending promise event . [[resultPromise]] with value .
11. Upon rejection of canMakePaymentPromise ,
    1. Resolve the pending promise event . [[resultPromise]] with false.

4.2.2 CanMakePaymentEventInit dictionary

dictionary CanMakePaymentEventInit : ExtendableEventInit {
    USVString                        topLevelOrigin;
    USVString                        paymentRequestOrigin;
    sequence<PaymentMethodData>      methodData;
    sequence<PaymentDetailsModifier> modifiers;
};

The topLevelOrigin , paymentRequestOrigin , methodData , and modifiers members share their definitions with those defined for PaymentRequestEvent .

5.1.1 onpaymentrequest attribute

The onpaymentrequest attribute is an event handler whose corresponding event handler event type is PaymentRequestEvent .

5.2.1 topLevelOrigin attribute

Returns a string that indicates the origin of the top level payee web page. This attribute is initialized by Handling a PaymentRequestEvent .

5.2.2 paymentRequestOrigin attribute

Returns a string that indicates the origin where a PaymentRequest was initialized. When a PaymentRequest is initialized in the topLevelOrigin , the attributes have the same value, otherwise the attributes have different values. For example, when a PaymentRequest is initialized within an iframe from an origin other than topLevelOrigin , the value of this attribute is the origin of the iframe. This attribute is initialized by Handling a PaymentRequestEvent .

5.2.3 paymentRequestId attribute

When getting, the paymentRequestId attribute returns the [[details]]. id from the PaymentRequest that corresponds to this PaymentRequestEvent .

5.2.4 methodData attribute

This attribute contains PaymentMethodData dictionaries containing the payment method identifiers for the payment methods that the web site accepts and any associated payment method specific data. It is populated from the PaymentRequest using the MethodData Population Algorithm defined below.

5.2.5 total attribute

This attribute indicates the total amount being requested for payment. It is of type PaymentCurrencyAmount dictionary as defined in [ payment-request ], and initialized with a structured clone of the total field of the PaymentDetailsInit provided when the corresponding PaymentRequest object was instantiated.

5.2.6 modifiers attribute

This sequence of PaymentDetailsModifier dictionaries contains modifiers for particular payment method identifiers (e.g., if the payment amount or currency type varies based on a per-payment-method basis). It is populated from the PaymentRequest using the Modifiers Population Algorithm defined below.

5.2.7 instrumentKey attribute

This attribute indicates the PaymentInstrument selected by the user. It corresponds to the instrumentKey provided to the PaymentManager.instruments interface during registration. An empty string means that the user did not choose a specific PaymentInstrument .

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

5.2.9 respondWith() method

This method is used by the 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 arguments.

5.2.10 PaymentRequestEventInit dictionary

dictionary PaymentRequestEventInit : ExtendableEventInit {
    USVString                        topLevelOrigin;
    USVString                        paymentRequestOrigin;
    DOMString                        paymentRequestId;
    sequence<PaymentMethodData>      methodData;
    PaymentCurrencyAmount            total;
    sequence<PaymentDetailsModifier> modifiers;
    DOMString                        instrumentKey;
};

The topLevelOrigin , paymentRequestOrigin , paymentRequestId , methodData , total , modifiers , and instrumentKey members share their definitions with those defined for PaymentRequestEvent

5.2.11 MethodData Population Algorithm

To initialize the value of the methodData , the user agent MUST perform the following steps or their equivalent:

1. Set registeredMethods to an empty set.
2. For each PaymentInstrument instrument in the payment handler 's PaymentManager . instruments , add the value of instrument . method to registeredMethods .
3. Create a new empty Sequence .
4. Set dataList to the newly created Sequence .
5. For each item in PaymentRequest @ [[methodData]] in the corresponding payment request, perform the following steps:
   1. Set inData to the item under consideration.
   2. Set commonMethods to the set intersection of inData . supportedMethods and registeredMethods .
   3. If commonMethods is empty, skip the remaining substeps and move on to the next item (if any).
   4. Create a new PaymentMethodData object.
   5. Set outData to the newly created PaymentMethodData .
   6. Set outData . supportedMethods to a list containing the members of commonMethods .
   7. Set outData .data to a structured clone of inData .data.
   8. Append outData to dataList .
6. Set methodData to dataList .

5.2.12 Modifiers Population Algorithm

To initialize the value of the modifiers , the user agent MUST perform the following steps or their equivalent:

1. Set registeredMethods to an empty set.
2. For each PaymentInstrument instrument in the payment handler 's PaymentManager . instruments , add the value of instrument . method to registeredMethods .
3. Create a new empty Sequence .
4. Set modifierList to the newly created Sequence .
5. For each item in PaymentRequest @ [[paymentDetails]] . modifiers in the corresponding payment request, perform the following steps:
   1. Set inModifier to the item under consideration.
   2. Set commonMethods to the set intersection of inModifier . supportedMethods and registeredMethods .
   3. If commonMethods is empty, skip the remaining substeps and move on to the next item (if any).
   4. Create a new PaymentDetailsModifier object.
   5. Set outModifier to the newly created PaymentDetailsModifier .
   6. Set outModifier . supportedMethods to a list containing the members of commonMethods .
   7. Set outModifier . total to a structured clone of inModifier . total .
   8. Append outModifier to modifierList .
6. Set modifiers to modifierList .

7.1.1 methodName attribute

The payment method identifier for the payment method that the user selected to fulfil the transaction.

7.1.2 details attribute

A JSON-serializable object that provides a payment method specific message used by the merchant to process the 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 respondWith() function of the corresponding PaymentRequestEvent interface. The application is expected to resolve the Promise with a PaymentHandlerResponse instance containing the payment response. In case of user cancellation or error, the application may signal failure by rejecting the Promise.

If the Promise is rejected, the user agent MUST run the payment app failure algorithm . The exact details of this algorithm are left to implementers. Acceptable behaviors include, but are not limited to:

• Letting the user try again, with the same payment handler or with a different one.
• Rejecting the Promise that was created by PaymentRequest.show() .