Features at risk

As this specification enters the Candidate Recommendation phase of the W3C standardization process, the working group has identified the following feature(s) as being "at risk" of being removed from the specification. The working group seeks input from implementers, developers, and the general public on whether these features should remain in the specification. If no compelling use cases are received, or if there is limited interest from implementers, these features will be removed from the specification before proceeding along the W3C Recommendation track.

• currencySystem (see issue 490).

Constructor

The PaymentRequest is constructed using the supplied methodData list including any payment method specific data, the payment details, and the payment options.

            const methodData = [{
              supportedMethods: "basic-card",
              data: {
                supportedNetworks: ['visa', 'mastercard'],
                supportedTypes: ['debit']
              }
            }, {
              supportedMethods: "https://example.com/bobpay",
              data: {
                merchantIdentifier: "XXXX",
                bobPaySpecificField: true
              }
            }];
            const request = new PaymentRequest(methodData, details, options);
          

            const details = {
              id: "super-store-order-123-12312",
              displayItems: [{
                label: "Sub-total",
                amount: { currency: "USD", value: "55.00" }, // US$55.00
              }, {
                label: "Sales Tax",
                amount: { currency: "USD", value: "5.00" }, // US$5.00
              }],
              total: {
                label: "Total due",
                amount: { currency: "USD", value: "60.00" }, // US$60.00
              }
            }
            const request = new PaymentRequest(methodData, details, options);
          

            const options = {
              requestShipping: true
            }
            const request = new PaymentRequest(methodData, details, options);
          

The PaymentRequest(methodData, details, options) constructor MUST act as follows:

1. If the current settings object's responsible document is not allowed to use the feature indicated by attribute name allowpaymentrequest, then throw a "SecurityError" DOMException.
2. Let serializedMethodData be an empty list.
3. Establish the request's id:
   1. If details.id is missing, add an id member to details and set its value to string that uniquely identifies this payment request. It is RECOMMENDED that the string be a UUID [[!RFC4122]].
4. Process payment methods:
   1. If the length of the methodData sequence is zero, then throw a TypeError, optionally informing the developer that at least one payment method is required.
   2. For each paymentMethod of methodData:
      1. If the data member of paymentMethod is missing, let serializedData be null. Otherwise, let serializedData be the result of JSON-serializing paymentMethod.data into a string. Rethrow any exceptions.
      2. Add the tuple (paymentMethod.supportedMethods, serializedData) to serializedMethodData.
5. Process the total:
   1. If details.total.amount.value is not a valid decimal monetary value, then throw a TypeError; optionally informing the developer that the value is invalid.
   2. If the first code point of details.total.amount.value is U+002D HYPHEN-MINUS, then throw a TypeError, optionally informing the developer that the total can't be negative.
6. If the displayItems member of details is present, then for each item in details.displayItems:
   1. If item.amount.value is not a valid decimal monetary value, then throw a TypeError, optionally informing the developer that the value is invalid.
7. Let selectedShippingOption be null.
8. Process shipping options:
   1. Let options be an empty sequence<PaymentShippingOption>.
   2. If the shippingOptions member of details is present, then:
      1. Let seenIDs be an empty list.
      2. Set options to details.shippingOptions.
      3. For each option in options:
         1. If option.amount.value is not a valid decimal monetary value, then throw a TypeError, optionally informing the developer that the value is invalid.
         2. If seenIDs contains option.id, then set options to an empty sequence and break.
         3. Append option.id to seenIDs.
      4. For each option in options (which may have been reset to the empty sequence in the previous step):
         1. If option.selected is true, then set selectedShippingOption to option.id.
   3. Set details.shippingOptions to options.
9. Let serializedModifierData be an empty list.
10. Process payment details modifiers:
    1. Let modifiers be an empty sequence<PaymentDetailsModifier>.
    2. If the modifiers member of details is present, then:
       1. Set modifiers to details.modifiers.
       2. For each modifier of modifiers:
          1. If the total member of modifier is present, then:
             1. Let value be modifier.total.amount.value.
             2. If value is not a valid decimal monetary value, then throw a TypeError, optionally informing the developer that the value is invalid.
             3. If the first code point of value is U+002D HYPHEN-MINUS, then throw a TypeError, optionally informing the developer that the value can't be negative.
          2. If the additionalDisplayItems member of modifier is present, then for each item of modifier.additionalDisplayItems:
             1. Let value be item.amount.value.
             2. If value is not a valid decimal monetary value, then throw a TypeError, optionally informing the developer that the value is invalid.
          3. If the data member of modifier is missing, let serializedData be null. Otherwise, let serializedData be the result of JSON-serializing modifier.data into a string. Rethrow any exceptions.
          4. Add serializedData to serializedModifierData.
          5. Remove the data member of modifier, if it is present.
    3. Set details.modifiers to modifiers.
11. Let request be a new PaymentRequest.
12. Set request.[[\options]] to options.
13. Set request.[[\state]] to "created".
14. Set request.[[\updating]] to false.
15. Set request.[[\details]] to details.
16. Set request.[[\serializedModifierData]] to serializedModifierData.
17. Set request.[[\serializedMethodData]] to serializedMethodData.
18. Set the value of request's shippingOption attribute to selectedShippingOption.
19. Set the value of the shippingAddress attribute on request to null.
20. If options.requestShipping is set to true, then set the value of the shippingType attribute on request to options.shippingType. Otherwise, set it to null.
21. Return request.

id attribute

When getting, the id attribute returns this PaymentRequest's [[\details]].id.

show() method

The show() method MUST act as follows:

1. Let request be the PaymentRequest object on which the method is called.

2. Optionally, if the user agent wishes to disallow the call to show() to protect the user, then return a promise rejected with a "SecurityError" DOMException. For example, the user agent may require the call to be triggered by user activation, or may limit the rate at which a page can call show(), as described in the the privacy considerations section.

   During the Candidate Recommendation phase, implementations are expected to experiment in this area. Developers using this API should investigate and anticipate such experiments and understand under what circumstances a "SecurityError" DOMException might occur. If interoperable behavior emerges amongst user agents, then that behavior will be standardized here before progressing the specification along the W3C Recommendation Track.

3. If request.[[\state]] is not "created" then return a promise rejected with an "InvalidStateError" DOMException.
4. If the user agent's payment request is showing boolean is true, then return a promise rejected with an "AbortError" DOMException.
5. Set request.[[\state]] to "interactive".
6. Let acceptPromise be a new Promise.
7. Set request.[[\acceptPromise]] to acceptPromise.

8. Optionally:

   1. Reject acceptPromise with an "AbortError" DOMException.
   2. Set request.[[\state]] to "closed".
   3. Return acceptPromise.

   This allows the user agent to act as if the user had immediately aborted the payment request, at its discretion. For example, in "private browsing" modes or similar, user agents might take advantage of this step.

9. Set the user agent's payment request is showing boolean to true.
10. Return acceptPromise and perform the remaining steps in parallel.
11. For each paymentMethod tuple in request.[[\serializedMethodData]]:
    1. Let identifier be the first element in the paymentMethod tuple.
    2. Let data be the result of JSON-parsing the second element in paymentMethod tuple.
    3. If required by the specification that defines the identifer, then convert data to an IDL value. Otherwise, convert to object.
    4. If conversion results in an error, reject acceptPromise with that error and terminate this algorithm.
    5. Determine which payment handlers support identifier. For each resulting payment handler, if payment method specific capabilities supplied by the payment handler match those provided by data, the payment handler matches.
12. If this consultation produced no supported method of paying, then reject acceptPromise with a "NotSupportedError" DOMException, and set the user agent's payment request is showing boolean to false.

13. Otherwise, show a user interface to allow the user to interact with the payment request process, using those payment handlers and payment methods which the above step identified as feasible. The user agent SHOULD prioritize the preference of the user when presenting payment methods and applications.

    The payment handler should be sent the appropriate data from request in order to guide the user through the payment process. This includes the various attributes and internal slots of request.

    The acceptPromise will later be resolved or rejected by either the user accepts the payment request algorithm or the user aborts the payment request algorithm, which are triggered through interaction with the user interface.

abort() method

The abort() method MUST act as follows:

1. Let request be the PaymentRequest object on which the method is called.
2. If the value of request.[[\state]] is not "interactive" then throw an "InvalidStateError" DOMException.
3. Let promise be a new Promise.
4. Return promise and perform the remaining steps in parallel.
5. Try to abort the current user interaction and close down any remaining user interface.
6. Queue a task on the user interaction task source to perform the following steps:
   1. If it is not possible to abort the current user interaction, then reject promise with "InvalidStateError" DOMException and abort these steps.
   2. Set the value of the internal slot request.[[\state]] to "closed".
   3. Reject the promise request.[[\acceptPromise]] with an "AbortError" DOMException.
   4. Resolve promise with undefined.

canMakePayment() method

The canMakePayment() method can be used by the developer to determine if the PaymentRequest object can be used to make a payment, before they call show(). It returns a Promise that will be fulfilled with true if the user agent supports any of the desired payment methods supplied to the PaymentRequest constructor, and false if none are supported. If the method is called too often, the user agent might instead return a promise rejected with a "NotAllowedError" DOMException, at its discretion.

The canMakePayment() method MUST act as follows:

1. Let request be the PaymentRequest object on which the method was called.
2. If request.[[\state]] is not "created", then return a promise rejected with an "InvalidStateError" DOMException.
3. Optionally, at the user agent's discretion, return a promise rejected with a "NotAllowedError" DOMException.

   This allows user agents to apply heuristics to detect and prevent abuse of the canMakePayment() method for fingerprinting purposes, such as creating PaymentRequest objects with a variety of supported payment methods and calling canMakePayment() on them one after the other. For example, a user agent may restrict the number of successful calls that can be made based on the top-level browsing context or the time period in which those calls were made.

4. Let promise be a new Promise.
5. Return promise, and perform the remaining steps in parallel.
6. For each methodData in request.[[\serializedMethodData]]:
   1. If methodData.supportedMethods is a supported payment method identifier (including its payment method specific capabilities), resolve promise with true, and abort this algorithm.
7. Resolve promise with false.

shippingAddress attribute

A PaymentRequest's shippingAddress attribute is populated when the user provides a shipping address. It is null by default. When a user provides a shipping address, the shipping address changed algorithm runs.

onshippingaddresschange attribute

A PaymentRequest's onshippingaddresschange attribute is an EventHandler for an Event named shippingaddresschange.

shippingOption attribute

A PaymentRequest's shippingOption attribute is populated when the user chooses a shipping option. It is null by default. When a user chooses a shipping option, the shipping option changed algorithm runs.

onshippingoptionchange attribute

A PaymentRequest's onshippingoptionchange attribute is an EventHandler for an Event named shippingoptionchange.

Internal Slots

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

Internal Slot	Description (non-normative)
[[\serializedMethodData]]	The methodData supplied to the constructor, but represented as tuples containing supported methods and a string or null for data (instead of the original object form).
[[\serializedModifierData]]	A list containing the serialized string form of each data member for each corresponding item in the sequence [[\details]].modifier, or null if no such member was present.
[[\details]]	The current PaymentDetailsBase for the payment request initially supplied to the constructor and then updated with calls to updateWith(). Note that all data members of PaymentDetailsModifier instances contained in the modifiers member will be removed, as they are instead stored in serialized form in the [[\serializedModifierData]] internal slot.
[[\options]]	The PaymentOptions supplied to the constructor.
[[\state]]	The current state of the payment request, which transitions from: "created" The payment request is constructed and has not been presented to the user. "interactive" The payment request is being presented to the user. "closed" The payment request completed. The state transitions are illustrated in the figure below:
[[\updating]]	true is there is a pending updateWith() call to update the payment request and false otherwise.
[[\acceptPromise]]	The pending Promise created during show that will be resolved if the user accepts the payment request.

PaymentDetailsBase dictionary

        dictionary PaymentDetailsBase {
          sequence<PaymentItem> displayItems;
          sequence<PaymentShippingOption> shippingOptions;
          sequence<PaymentDetailsModifier> modifiers;
        };
      

The following members are part of the PaymentDetailsBase dictionary:

displayItems

This sequence of PaymentItem dictionaries contains line items for the payment request that the user agent MAY display. For example, it might include details of products or breakdown of tax and shipping. It is optional to provide this information.

It is the developer's responsibility to verify that the total amount is the sum of these items.

shippingOptions

A sequence containing the different shipping options for the user to choose from.

If the sequence is empty, then this indicates that the merchant cannot ship to the current shippingAddress.

If an item in the sequence has the selected member set to true, then this is the shipping option that will be used by default and shippingOption will be set to the id of this option without running the shipping option changed algorithm. Authors SHOULD NOT set selected to true on more than one item. If more than one item in the sequence has selected set to true, then user agents MUST select the last one in the sequence.

The shippingOptions member is only used if the PaymentRequest was constructed with PaymentOptions requestShipping set to true.

If the sequence has an item with the selected member set to true, then authors are responsible for ensuring that the total member includes the cost of the shipping option. This is because no shippingoptionchange event will be fired for this option unless the user selects an alternative option first.

modifiers

This sequence of PaymentDetailsModifier dictionaries contains modifiers for particular payment method identifiers. For example, it allows you to adjust the total amount based on payment method.

PaymentDetailsInit dictionary

        dictionary PaymentDetailsInit : PaymentDetailsBase {
          DOMString id;
          required PaymentItem total;
        };
      

The PaymentDetailsInit dictionary is used in the construction of the payment request.

In addition to the members inherited from the PaymentDetailsBase dictionary, the following members are part of the PaymentDetailsInit dictionary:

id

id is a free-form identifier for this payment request.

If an id member is not present, then the user agent will generate a unique identifier for the payment request during construction.

total

This PaymentItem contains the non-negative total amount of the payment request.

Algorithms in this specification that accept a PaymentDetailsInit dictionary will throw if the total.amount.value is a negative number.

PaymentDetailsUpdate dictionary

        dictionary PaymentDetailsUpdate : PaymentDetailsBase {
          DOMString error;
          PaymentItem total;
        };
      

The PaymentDetailsUpdate dictionary is used to update the payment request using updateWith().

In addition to the members inherited from the PaymentDetailsBase dictionary, the following members are part of the PaymentDetailsUpdate dictionary:

error

When the payment request is updated using updateWith(), the PaymentDetailsUpdate can contain a message in the error member that will be displayed to the user, if the PaymentDetailsUpdate indicates that there are no valid shippingOptions (and the PaymentRequest was constructed with the requestShipping option set to true). This can be used to explain why goods cannot be shipped to the chosen shipping address, or any other reason why no shipping options are available.

total

This PaymentItem contains the non-negative total amount.

Algorithms in this specification that accept a PaymentDetailsUpdate dictionary will throw if the total.amount.value is a negative number.

toJSON() method

When called, run [[!WEBIDL]]'s default toJSON operation.

country attribute

This is the [[!CLDR]] (Common Locale Data Repository) region code. For example, US, GB, CN, or JP.

addressLine attribute

This is the most specific part of the address. It can include, for example, a street name, a house number, apartment number, a rural delivery route, descriptive instructions, or a post office box number.

region attribute

This is the top level administrative subdivision of the country. For example, this can be a state, a province, an oblast, or a prefecture.

city attribute

This is the city/town portion of the address.

dependentLocality attribute

This is the dependent locality or sublocality within a city. For example, used for neighborhoods, boroughs, districts, or UK dependent localities.

postalCode attribute

This is the postal code or ZIP code, also known as PIN code in India.

sortingCode attribute

This is the sorting code as used in, for example, France.

languageCode attribute

This is the [[!BCP47]] language code for the address. It's used to determine the field separators and the order of fields when formatting the address for display.

organization attribute

This is the organization, firm, company, or institution at this address.

recipient attribute

This is the name of the recipient or contact person. This member may, under certain circumstances, contain multiline information. For example, it might contain "care of" information.

phone attribute

This is the phone number of the recipient or contact person.

toJSON() method

When called, run [[!WEBIDL]]'s default toJSON operation.

methodName attribute

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

details attribute

An object that provides a payment method specific message used by the merchant to process the transaction and determine successful fund transfer. This data is returned by the payment method specific code that satisfies the payment request.

shippingAddress attribute

If the requestShipping flag was set to true in the PaymentOptions passed to the PaymentRequest constructor, then shippingAddress will be the full and final shipping address chosen by the user.

shippingOption attribute

If the requestShipping flag was set to true in the PaymentOptions passed to the PaymentRequest constructor, then shippingOption will be the id attribute of the selected shipping option.

payerName attribute

If the requestPayerName flag was set to true in the PaymentOptions passed to the PaymentRequest constructor, then payerName will be the name provided by the user.

payerEmail attribute

If the requestPayerEmail flag was set to true in the PaymentOptions passed to the PaymentRequest constructor, then payerEmail will be the email address chosen by the user.

payerPhone attribute

If the requestPayerPhone flag was set to true in the PaymentOptions passed to the PaymentRequest constructor, then payerPhone will be the phone number chosen by the user.

requestId attribute

The corresponding payment request id that spawned this payment response.

complete() method

The complete() method is called after the user has accepted the payment request and the [[\acceptPromise]] has been resolved. Calling the complete() method tells the user agent that the transaction is over (and SHOULD cause any remaining user interface to be closed).

After the payment request has been accepted and the PaymentResponse returned to the caller but before the caller calls complete() the payment request user interface remains in a pending state. At this point the user interface ought not offer a cancel command because acceptance of the payment request has been returned. However, if something goes wrong and the developer never calls complete() then the user interface is blocked.

For this reason, implementations MAY impose a timeout for developers to call complete(). If the timeout expires then the implementation will behave as if complete() was called with no arguments.

The complete(result) method MUST act as follows:

1. Let promise be a new Promise.
2. If the value of the internal slot [[\completeCalled]] is true, reject promise with an "InvalidStateError" DOMException.
3. Otherwise, set the value of the internal slot [[\completeCalled]] to true.
4. Return promise and perform the remaining steps in parallel.
5. Close down any remaining user interface. The user agent MAY use the value result to influence the user experience.
6. Resolve promise with undefined.

Internal Slots

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

PaymentRequestUpdateEvent interface

          [Constructor(DOMString type, optional PaymentRequestUpdateEventInit eventInitDict),SecureContext]
          interface PaymentRequestUpdateEvent : Event {
            void updateWith(Promise<PaymentDetailsUpdate> detailsPromise);
          };
        

The PaymentRequestUpdateEvent enables developers to update the details of the payment request in response to a user interaction.

If a developer wants to update the payment request, then they need to call updateWith() and provide a PaymentDetailsUpdate dictionary, or a promise for one, containing changed values that the user agent SHOULD present to the user.

The PaymentRequestUpdateEvent constructor MUST set the internal slot [[\waitForUpdate]] to false.

            dictionary PaymentRequestUpdateEventInit : EventInit {};
          

Shipping address changed algorithm

The shipping address changed algorithm runs when the user provides a new shipping address. It MUST run the following steps:

1. Let request be the PaymentRequest object that the user is interacting with.
2. Let name be "shippingaddresschange".
3. Queue a task on the user interaction task source to run the following steps:
   1. Set the shippingAddress attribute on request to the shipping address provided by the user.
   2. Run the PaymentRequest updated algorithm with request and name.

Shipping option changed algorithm

The shipping option changed algorithm runs when the user chooses a new shipping option. It MUST run the following steps:

1. Let request be the PaymentRequest object that the user is interacting with.
2. Let name be "shippingoptionchange".
3. Queue a task on the user interaction task source to run the following steps:
   1. Set the shippingOption attribute on request to the id string of the PaymentShippingOption provided by the user.
   2. Run the PaymentRequest updated algorithm with request and name.

PaymentRequest updated algorithm

The PaymentRequest updated algorithm is run by other algorithms above to fire an event to indicate that a user has made a change to a PaymentRequest called request with an event name of name.

It MUST run the following steps:

1. If the request.[[\updating]] is true, then terminate this algorithm and take no further action. Only one update may take place at a time. This should never occur.
2. If the request.[[\state]] is not set to "interactive", then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
3. Fire an event named name at request using PaymentRequestUpdateEvent.

User accepts the payment request algorithm

The user accepts the payment request algorithm runs when the user accepts the payment request and confirms that they want to pay. It MUST queue a task on the user interaction task source to perform the following steps:

1. Let request be the PaymentRequest object that the user is interacting with.
2. If the request.[[\updating]] is true, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
3. If request.[[\state]] is not "interactive", then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
4. If the requestShipping value of request.[[\options]] is true, then if the shippingAddress attribute of request is null or if the shippingOption attribute of request is null, then terminate this algorithm and take no further action. This should never occur.
5. Let response be a new PaymentResponse.
6. Set the requestId attribute value of response to the value of request.[[\details]].id.
7. Set the methodName attribute value of response to the payment method identifier for the payment method that the user selected to accept the payment.
8. Set the details attribute value of response to an object containing the payment method specific message that will be used by the merchant to process the transaction. The format of this response will be defined for each payment method.
9. If the requestShipping value of request.[[\options]] is true, then set the shippingAddress attribute of response to the value of the shippingAddress attribute of request. Otherwise, set it to null.
10. If the requestShipping value of request.[[\options]] is true, then set the shippingOption attribute of response to the value of the shippingOption attribute of request. Otherwise, set it to null.
11. If the requestPayerName value of request.[[\options]] is true, then set the payerName attribute of response to the payer's name provided by the user, or to null if none was provided. Otherwise, set it to null.
12. If the requestPayerEmail value of request.[[\options]] is true, then set the payerEmail attribute of response to the payer's email address provided by the user, or to null if none was provided. Otherwise, set it to null.
13. If the requestPayerPhone value of request.[[\options]] is true, then set the payerPhone attribute of response to the payer's phone number provided by the user, or to null if none was provided. When setting the payerPhone value, the user agent SHOULD format the phone number to adhere to [[!E.164]]. Otherwise, set it to null.
14. Set response.[[\completeCalled]] to false.
15. Set request.[[\state]] to "closed".
16. Set the user agent's payment request is showing boolean to false.
17. Resolve the pending promise request.[[\acceptPromise]] with response.

User aborts the payment request algorithm

The user aborts the payment request algorithm runs when the user aborts the payment request through the currently interactive user interface. It MUST queue a task on the user interaction task source to perform the following steps:

1. Let request be the PaymentRequest object that the user is interacting with.
2. If the request.[[\updating]] is true, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
3. If request.[[\state]] is not "interactive", then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
4. Set request.[[\state]] to "closed".
5. Set the user agent's payment request is showing boolean to false.
6. Reject the promise request.[[\acceptPromise]] with an "AbortError" DOMException.