Payment Request API

3.1 Constructor

The PaymentRequest is constructed using the supplied sequence of PaymentMethodData methodData including any payment method specific data, the PaymentDetailsInit details, and the PaymentOptions 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 "payment" feature, then throw a "SecurityError" DOMException.
2. Establish the request's id:
   1. If details.id is missing, add an id member to details and set its value to a UUID [RFC4122].
3. Let serializedMethodData be an empty list.
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. Run the steps to validate a payment method identifier with paymentMethod.supportedMethods. If it returns false, then throw a "RangeError" exception. Optionally, inform the developer that the payment method identifier is invalid.
      2. 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.
      3. If serializedData is not null, and if required by the specification that defines the paymentMethod.supportedMethods:
         1. Let object be the result of JSON-parsing serializedData.

         2. Convert object to an IDL value of the type specified by the specification that defines the paymentMethod.supportedMethods (e.g., a BasicCardRequest in the case of [payment-method-basic-card]). Rethrow any exceptions.

            Note

            This step assures that any IDL type conversion errors are caught as early as possible.

      4. Add the tuple (paymentMethod.supportedMethods, serializedData) to serializedMethodData.
5. Process the total:
   1. Check and canonicalize total amount details.total.amount. Rethrow any exceptions.
6. If the displayItems member of details is present, then for each item in details.displayItems:
   1. Check and canonicalize amount item.amount. Rethrow any exceptions.
7. Let selectedShippingOption be null.
8. If the requestShipping member of options is present and set to true, 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 set.
      2. For each option in details.shippingOptions:
         1. Check and canonicalize amount item.amount. Rethrow any exceptions.
         2. If seenIDs contains option.id, then throw a TypeError. Optionally, inform the developer that shipping option IDs must be unique.
         3. Otherwise, append option.id to seenIDs.
         4. 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. Check and canonicalize total amount modifier.total.amount. Rethrow any exceptions.
          2. If the additionalDisplayItems member of modifier is present, then for each item of modifier.additionalDisplayItems:
             1. Check and canonicalize amount item.amount. Rethrow any exceptions.
          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 the tuple (modifier.supportedMethods, 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 request.[[response]] to null.
19. Set the value of request's shippingOption attribute to selectedShippingOption.
20. Set the value of the shippingAddress attribute on request to null.
21. 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.
22. Return request.

3.2 id attribute

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

3.3 show() method

The show(optional detailsPromise) method MUST act as follows:

1. If the relevant global object of this does not have transient activation, return a promise rejected with with a "SecurityError" DOMException.
2. Let request be the context object.
3. Let document be request's relevant global object's associated Document.
4. If document is not fully active, then return a promise rejected with an "AbortError" DOMException.

5. 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 limit the rate at which a page can call show(), as described in section § 19. Privacy and Security Considerations .

6. If request.[[state]] is not "created" then return a promise rejected with an "InvalidStateError" DOMException.
7. If the user agent's payment request is showing boolean is true, then:
   1. Set request.[[state]] to "closed".
   2. Return a promise rejected with an "AbortError" DOMException.
8. Set request.[[state]] to "interactive".
9. Let acceptPromise be a new promise.
10. Set request.[[acceptPromise]] to acceptPromise.

11. Optionally:

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

    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.

12. Set request's payment-relevant browsing context's payment request is showing boolean to true.
13. Return acceptPromise and perform the remaining steps in parallel.
14. Let handlers be an empty list.
15. 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 the paymentMethod tuple.
    3. If required by the specification that defines the identifier, then convert data to an IDL value of the type specified there. Otherwise, convert to object.
    4. If conversion results in an exception error:
       1. Set request.[[state]] to "closed".
       2. Reject acceptPromise with error.
       3. Set request's payment-relevant browsing context's payment request is showing boolean to false.
       4. Terminate this algorithm.
    5. Let registeredHandlers be a list of registered payment handlers for the payment method identifier.
    6. For each handler in registeredHandlers:
       1. Let canMakePayment be the result of running handler's steps to check if a payment can be made with data.
       2. If canMakePayment is true, then append handler to handlers.
16. If handlers is empty, then:
    1. Set request.[[state]] to "closed".
    2. Reject acceptPromise with "NotSupportedError" DOMException.
    3. Set request's payment-relevant browsing context's payment request is showing boolean to false.
    4. Terminate this algorithm.
17. Present a user interface that will allow the user to interact with the handlers. The user agent SHOULD prioritize the preference of the user when presenting payment methods. It is RECOMMENDED that the language of the user interface match the language of the body element.
18. If detailsPromise was passed, then:
    1. Run the update a PaymentRequest's details algorithm with detailsPromise, request, and null.
    2. Wait for the detailsPromise to settle.
       Note

       Based on how the detailsPromise settles, the update a PaymentRequest's details algorithm determines how the payment UI behaves. That is, upon rejection of the detailsPromise, the payment request aborts. Otherwise, upon fulfillment detailsPromise, the user agent re-enables the payment request UI and the payment flow can continue.

19. Let handler be the payment handler selected by the end-user.
20. Let modifiers be an empty list.
21. For each tuple in [[serializedModifierData]]:
    1. If the first element of tuple (a PMI) matches the payment method identifier of handler, then append the second element of tuple (the serialized method data) to modifiers.

22. Pass the converted second element in the paymentMethod tuple and modifiers. Optionally, the user agent SHOULD send the appropriate data from request to the user-selected payment handler in order to guide the user through the payment process. This includes the various attributes and other internal slots of request (some MAY be excluded for privacy reasons where appropriate).

    Handling of multiple applicable modifiers in the [[serializedModifierData]] internal slot is payment handler specific and beyond the scope of this specification. Nevertheless, it is RECOMMENDED that payment handlers use a "last one wins" approach with items in the [[serializedModifierData]] list: that is to say, an item at the end of the list always takes precedence over any item at the beginning of the list (see example below).

    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.

    If document stops being fully active while the user interface is being shown, or no longer is by the time this step is reached, then:

    1. Close down the user interface.
    2. Set request's payment-relevant browsing context's payment request is showing boolean to false.

3.4 abort() method

The abort() method MUST act as follows:

1. Let request be the context object.
2. If request.[[response]] is not null, and request.[[response]].[[retryPromise]] is not null, return a promise rejected with an "InvalidStateError" DOMException.
3. If the value of request.[[state]] is not "interactive" then return a promise rejected with an "InvalidStateError" DOMException.
4. Let promise be a new promise.
5. Return promise and perform the remaining steps in parallel.
6. Try to abort the current user interaction with the payment handler and close down any remaining user interface.
7. 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 request.[[state]] to "closed".
   3. Reject the promise request.[[acceptPromise]] with an "AbortError" DOMException.
   4. Resolve promise with undefined.

3.5 canMakePayment() method

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 top-level browsing context's discretion, return a promise rejected with a "NotAllowedError" DOMException. As described in section § 19.9 canMakePayment() protections , the user agent may limit the rate at which a page can call canMakePayment().
4. Let hasHandlerPromise be a new promise.
5. Return hasHandlerPromise, and perform the remaining steps in parallel.
6. For each paymentMethod tuple in request.[[serializedMethodData]]:
   1. Let identifier be the first element in the paymentMethod tuple.
   2. If the user agent has a payment handler that supports handling payment requests for identifier, resolve hasHandlerPromise with true and terminate this algorithm.
7. Resolve hasHandlerPromise with false.

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

3.7 shippingType attribute

A PaymentRequest's shippingType attribute is the type of shipping used to fulfill the transaction. Its value is either a PaymentShippingType enum value, or null if none is provided by the developer during construction (see PaymentOptions's shippingType member).

3.8 onmerchantvalidation attribute

A PaymentRequest's onmerchantvalidation attribute is an EventHandler for a MerchantValidationEvent named "merchantvalidation".

3.9 onshippingaddresschange attribute

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

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

3.11 onshippingoptionchange attribute

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

3.12 onpaymentmethodchange attribute

A PaymentRequest's onpaymentmethodchange attribute is an EventHandler for a PaymentMethodChangeEvent named "paymentmethodchange".

3.13 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 if 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.
[[response]]	Null, or the PaymentResponse instantiated by this PaymentRequest.

5.1 Validity checkers

A JavaScript string is a valid decimal monetary value if it consists of the following code points in the given order:

1. Optionally, a single U+002D (-), to indicate that the amount is negative.
2. One or more code points in the range U+0030 (0) to U+0039 (9).
3. Optionally, a single U+002E (.) followed by one or more code points in the range U+0030 (0) to U+0039 (9).

^-?[0-9]+(\.[0-9]+)?$

To check and canonicalize amount given a PaymentCurrencyAmount amount, run the following steps:

1. If the result of IsWellFormedCurrencyCode(amount.currency) is false, then throw a "RangeError" exception, optionally informing the developer that the currency is invalid.
2. If amount.value is not a valid decimal monetary value, throw a TypeError, optionally informing the developer that the currency is invalid.
3. Set amount.currency to the result of ASCII uppercase amount.currency.

To check and canonicalize total amount given a PaymentCurrencyAmount amount, run the following steps:

1. Check and canonicalize amount amount. Rethrow any exceptions.
2. If the first code point of amount.value is U+002D (-), then throw a TypeError optionally informing the developer that a total's value can't be a negative number.

6.1 PaymentDetailsBase dictionary

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

displayItems member

A sequence of PaymentItem dictionaries contains line items for the payment request that the user agent MAY display.

Note

shippingOptions member

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

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. If more than one item in the sequence has selected set to true, then the user agent selects the last one in the sequence.

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

Note

modifiers member

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

6.2 PaymentDetailsInit dictionary

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

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

id member

A free-form identifier for this payment request.

Note

total member

A PaymentItem containing a non-negative total amount for the payment request.

Note

6.3 PaymentDetailsUpdate dictionary

dictionary PaymentDetailsUpdate : PaymentDetailsBase {
  DOMString error;
  PaymentItem total;
  AddressErrors shippingAddressErrors;
  PayerErrors payerErrors;
  object paymentMethodErrors;
};

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 member

A human-readable string that explains why goods cannot be shipped to the chosen shipping address, or any other reason why no shipping options are available. 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).

total member

A PaymentItem containing a non-negative amount.

Note

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

shippingAddressErrors member

Represents validation errors with the shipping address that is associated with the potential event target.

payerErrors member

Validation errors related to the payer details.

paymentMethodErrors member

Payment method specific errors. See, for example, [payment-method-basic-card]'s BasicCardErrors.

11.1 PaymentAddress interface

[SecureContext, Exposed=(Window)]
interface PaymentAddress {
  [Default] object toJSON();
  readonly attribute DOMString city;
  readonly attribute DOMString country;
  readonly attribute DOMString dependentLocality;
  readonly attribute DOMString organization;
  readonly attribute DOMString phone;
  readonly attribute DOMString postalCode;
  readonly attribute DOMString recipient;
  readonly attribute DOMString region;
  readonly attribute DOMString sortingCode;
  readonly attribute FrozenArray<DOMString> addressLine;
};

The PaymentAddress interface represents a physical address.

11.2 AddressInit dictionary

dictionary AddressInit {
  DOMString country;
  sequence<DOMString> addressLine;
  DOMString region;
  DOMString city;
  DOMString dependentLocality;
  DOMString postalCode;
  DOMString sortingCode;
  DOMString organization;
  DOMString recipient;
  DOMString phone;
};

An AddressInit is passed when constructing a PaymentAddress. Its members are as follows.

addressLine member

An address line, represented as a sequence.

city member

A city.

country member

An country, represented as a [ISO3166-1] country code.

dependentLocality member

A dependent locality.

organization member

An organization.

phone member

A phone number, optionally structured to adhere to [E.164].

postalCode member

A postal code.

recipient member

A recipient. Under certain circumstances, this member may contain multiline information. For example, it might contain "care of" information.

region member

A region.

sortingCode member

A sorting code.

11.3 AddressErrors dictionary

dictionary AddressErrors {
  DOMString addressLine;
  DOMString city;
  DOMString country;
  DOMString dependentLocality;
  DOMString organization;
  DOMString phone;
  DOMString postalCode;
  DOMString recipient;
  DOMString region;
  DOMString sortingCode;
};

The members of the AddressErrors dictionary represent validation errors with specific parts of a physical address. Each dictionary member has a dual function: firstly, its presence denotes that a particular part of an address is suffering from a validation error. Secondly, the string value allows the developer to describe the validation error (and possibly how the end user can fix the error).

addressLine member

Denotes that the address line has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress's addressLine attribute's value.

city member

Denotes that the city has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress's city attribute's value.

country member

Denotes that the country has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress's country attribute's value.

dependentLocality member

Denotes that the dependent locality has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress's dependentLocality attribute's value.

organization member

Denotes that the organization has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress's organization attribute's value.

phone member

Denotes that the phone number has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress's phone attribute's value.

postalCode member

Denotes that the postal code has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress's postalCode attribute's value.

recipient member

Denotes that the recipient has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress's addressLine attribute's value.

region member

Denotes that the region has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress's region attribute's value.

sortingCode member

The sorting code has a validation error. In the user agent's UI, this member corresponds to the input field that provided the PaymentAddress's sortingCode attribute's value.

11.4 Creating a PaymentAddress from user-provided input

The steps to create a PaymentAddress from user-provided input are given by the following algorithm. The algorithm takes a list redactList.

1. Let details be an AddressInit dictionary with no members present.
2. If "addressLine" is not in redactList, set details["addressLine"] to the result of splitting the user-provided address line into a list. If none was provided, set it to the empty list.
   Note
3. If "country" is not in redactList, set details["country"] to the user-provided country as an upper case [ISO3166-1] alpha-2 code, or to the empty string if none was provided.
4. If "phone" is not in redactList, set details["phone"] to the user-provided phone number, or to the empty string if none was provided.
   Note: Privacy of phone number
5. If "city" is not in redactList, set details["city"] to the user-provided city, or to the empty string if none was provided.
6. If "dependentLocality" is not in redactList, set details["dependentLocality"] to the user-provided dependent locality, or to the empty string if none was provided.
7. If "organization" is not in redactList, set details["organization"] to the user-provided recipient organization, or to the empty string if none was provided.
8. If "postalCode" is not in redactList, set details["postalCode"] to the user-provided postal code, or to the empty string if none was provided. Optionally, redact part of details["postalCode"].
   Note: Privacy of Postal Codes

   Postal codes in certain countries can be so specific as to uniquely identify an individual. This being a privacy concern, some user agents only return the part of a postal code that they deem sufficient for a merchant to calculate shipping costs. This varies across countries and regions, and so the choice to redact part, or all, of the postal code is left to the discretion of implementers in the interest of protecting users' privacy.

9. If "recipient" is not in redactList, set details["recipient"] to the user-provided recipient of the transaction, or to the empty string if none was provided.

10. If "region" is not in redactList:

    Note: Countries where regions are not commonly used

    In some countries (e.g., Belgium) it is uncommon for users to include a region as part of a physical address (even if all the regions of a country are part of [ISO3166-2]). As such, when the user agent knows that the user is inputting the address for a particular country, it might not provide a field for the user to input a region. In such cases, the user agent returns an empty string for both PaymentAddress's region attribute - but the address can still serve its intended purpose (e.g., be valid for shipping or billing purposes).

    1. Set details["region"] to the user-provided region, or to the empty string if none was provided.
11. If "sortingCode" is not in redactList, set details["sortingCode"] to the user-provided sorting code, or to the empty string if none was provided.
12. Internally construct a new PaymentAddress with details and return the result.

14.1 retry() method

The retry(errorFields) method MUST act as follows:

1. Let response be the context object.
2. Let request be response.[[request]].
3. Let document be request's relevant global object's associated Document.
4. If document is not fully active, then return a promise rejected with an "AbortError" DOMException.
5. If response.[[complete]] is true, return a promise rejected with an "InvalidStateError" DOMException.
6. If response.[[retryPromise]] is not null, return a promise rejected with an "InvalidStateError" DOMException.
7. Set request.[[state]] to "interactive".
8. Let retryPromise be a new promise.
9. Set response.[[retryPromise]] to retryPromise.
10. If errorFields was passed:
    1. Optionally, show a warning in the developer console if any of the following are true:
       1. request.[[options]]["requestPayerName"] is false, and errorFields["payer"]["name"] is present.
       2. request.[[options]]["requestPayerEmail"] is false, and errorFields["payer"]["email"] is present.
       3. request.[[options]]["requestPayerPhone"] is false, and errorFields["payer"]["phone"] is present.
       4. request.[[options]]["requestShipping"] is false, and errorFields["shippingAddress"] is present.
    2. If errorFields["paymentMethod] member was passed, and if required by the specification that defines response's payment method, then convert errorFields's paymentMethod member to an IDL value of the type specified there. Otherwise, convert to object.
    3. Set request's payment-relevant browsing context's payment request is showing boolean to false.
    4. If conversion results in a exception error:
       1. Reject retryPromise with error.
       2. Set user agent's payment request is showing boolean to false.
       3. Return.
    5. By matching the members of errorFields to input fields in the user agent's UI, indicate to the end user that something is wrong with the data of the payment response. For example, a user agent might draw the user's attention to the erroneous errorFields in the browser's UI and display the value of each field in a manner that helps the user fix each error. Similarly, if the error member is passed, present the error in the user agent's UI. In the case where the value of a member is the empty string, the user agent MAY substitute a value with a suitable error message.
11. Otherwise, if errorFields was not passed, signal to the end user to attempt to retry the payment. Re-enable any UI element that affords the end user the ability to retry accepting the payment request.
12. If document stops being fully active while the user interface is being shown, or no longer is by the time this step is reached, then:
    1. Close down the user interface.
    2. Set request's payment-relevant browsing context's payment request is showing boolean to false.
13. Finally, when retryPromise settles, set response.[[retryPromise]] to null.
14. Return retryPromise.
    Note

    The retryPromise will later be resolved by the user accepts the payment request algorithm, or rejected by either the user aborts the payment request algorithm or abort the update.

dictionary PaymentValidationErrors {
  PayerErrors payer;
  AddressErrors shippingAddress;
  DOMString error;
  object paymentMethod;
};

dictionary PayerErrors {
  DOMString email;
  DOMString name;
  DOMString phone;
};

const payer = {
  email: "The domain is invalid.",
  phone: "Unknown country code.",
  name: "Not in database.",
};
await response.retry({ payer });

14.2 toJSON() method

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

14.3 methodName attribute

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

14.4 details attribute

An object or dictionary generated by a payment method that a merchant can use to process or validate a transaction (depending on the payment method).

14.5 shippingAddress attribute

If the requestShipping member 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.

14.6 shippingOption attribute

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

14.7 payerName attribute

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

14.8 payerEmail attribute

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

14.9 payerPhone attribute

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

14.10 requestId attribute

The corresponding payment request id that spawned this payment response.

14.11 complete() method

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 SHOULD 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 response be the context object.
2. If response.[[complete]] is true, return a promise rejected with an "InvalidStateError" DOMException.
3. If response.[[retryPromise]] is not null, return a promise rejected with an "InvalidStateError" DOMException.
4. Let promise be a new promise.
5. Set response.[[complete]] to true.
6. Return promise and perform the remaining steps in parallel.
7. If document stops being fully active while the user interface is being shown, or no longer is by the time this step is reached, then:
   1. Close down the user interface.
   2. Set request's payment-relevant browsing context's payment request is showing boolean to false.
8. Otherwise:
   1. Close down any remaining user interface. The user agent MAY use the value result to influence the user experience.
   2. Set request's payment-relevant browsing context's payment request is showing boolean to false.
   3. Resolve promise with undefined.

14.12 onpayerdetailchange attribute

Allows a developer to handle "payerdetailchange" events.

14.13 Internal Slots

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

17.2 MerchantValidationEvent interface

[SecureContext, Exposed=Window]
interface MerchantValidationEvent : Event {
  constructor(DOMString type, optional MerchantValidationEventInit eventInitDict = {});
  readonly attribute DOMString methodName;
  readonly attribute USVString validationURL;
  void complete(Promise<any> merchantSessionPromise);
};

dictionary MerchantValidationEventInit : EventInit {
  DOMString methodName = "";
  USVString validationURL = "";
};

17.3 PaymentMethodChangeEvent interface

[SecureContext, Exposed=Window]
interface PaymentMethodChangeEvent : PaymentRequestUpdateEvent {
  constructor(DOMString type, optional PaymentMethodChangeEventInit eventInitDict = {});
  readonly attribute DOMString methodName;
  readonly attribute object? methodDetails;
};

dictionary PaymentMethodChangeEventInit : PaymentRequestUpdateEventInit {
  DOMString methodName = "";
  object? methodDetails = null;
};

17.4 PaymentRequestUpdateEvent interface

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

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

dictionary PaymentRequestUpdateEventInit : EventInit {};

18.1 Merchant validation

Merchant validation is the process by which a payment handler validates the identity of a merchant against some value (usually some cryptographic challenge response). Validated merchants are allowed to interface with a payment handler. Details of how actual validation is performed is outside the scope of this specification.

It is OPTIONAL for a payment handler to support merchant validation.

For payment methods that support merchant validation, the user agent runs the request merchant validation algorithm. The algorithm takes a USVString merchantSpecificURL, provided by the payment handler:

1. Let request be the PaymentRequest object that the user is interacting with.
2. Let validationURL be a absolute-URL string from which a developer can fetch payment handler-specific verification data.
3. Let methodName be the payment method identifier for the payment handler that is requiring merchant validation.
4. Queue a task on the user interaction task source to run the following steps:
   1. Assert: request.[[updating]] is false.
   2. Assert: request.[[state]] is "interactive".
   3. Let eventInitDict be an new MerchantValidationEventInit dictionary.
   4. Set eventInitDict["validationURL"] to validationURL.
   5. Set eventInitDict["methodName"] to methodName.
   6. Let event be the result of calling the constructor of MerchantValidationEvent with "merchantvalidation" and eventInitDict.
   7. Initialize event’s Event.isTrusted attribute to true.
   8. Dispatch event to request.

18.2 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. Queue a task on the user interaction task source to run the following steps:
   1. Note: Privacy of recipient information

      The redactList limits the amount of personal information about the recipient that the API shares with the merchant.

      For merchants, the resulting PaymentAddress object provides enough information to, for example, calculate shipping costs, but, in most cases, not enough information to physically locate and uniquely identify the recipient.

      Unfortunately, even with the redactList, recipient anonymity cannot be assured. This is because in some countries postal codes are so fine-grained that they can uniquely identify a recipient.

   2. Let redactList be the empty list. Set redactList to « "organization", "phone", "recipient", "addressLine" ».
   3. Let address be the result of running the steps to create a PaymentAddress from user-provided input with redactList.
   4. Set the shippingAddress attribute on request to address.
   5. Run the PaymentRequest updated algorithm with request and "shippingaddresschange".

18.3 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. 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 "shippingoptionchange".

18.4 Payment method changed algorithm

A payment handler MAY run the payment method changed algorithm when the user changes payment method with methodDetails, which is a dictionary or an object or null, and a methodName, which is a DOMString that represents the payment method identifier of the payment handler the user is interacting with.

1. Let request be the PaymentRequest object that the user is interacting with.
2. Queue a task on the user interaction task source to run the following steps:
   1. Assert: request.[[updating]] is false. Only one update can take place at a time.
   2. Assert: request.[[state]] is "interactive".
   3. Fire an event named "paymentmethodchange" at request using PaymentMethodChangeEvent, with its methodName attribute initialized to methodName, and its methodDetails attribute initialized to methodDetails.

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

1. Assert: request.[[updating]] is false. Only one update can take place at a time.
2. Assert: request.[[state]] is "interactive".
3. Let event be the result of creating an event using the PaymentRequestUpdateEvent interface.
4. Initialize event's type attribute to name.
5. Dispatch event at request.
6. If event.[[waitForUpdate]] is true, disable any part of the user interface that could cause another update event to be fired.
7. Otherwise, set event.[[waitForUpdate]] to true.

18.6 Payer detail changed algorithm

The user agent MUST run the payer detail changed algorithm when the user changes the payer name, or the payer email, or the payer phone in the user interface:

1. Let request be the PaymentRequest object that the user is interacting with.
2. If request.[[response]] is null, return.
3. Let response be request.[[response]].
4. Queue a task on the user interaction task source to run the following steps:
   1. Assert: request.[[updating]] is false.
   2. Assert: request.[[state]] is "interactive".
   3. Let options be request.[[options]].
   4. If payer name changed and options.requestPayerName is true:
      1. Set response's payerName attribute to payer name.
   5. If payer email changed and options.requestPayerEmail is true:
      1. Set response's payerEmail attribute to payer email.
   6. If payer phone changed and options.requestPayerPhone is true:
      1. Set response's payerPhone attribute to payer phone.
   7. Let event be the result of creating an event using PaymentRequestUpdateEvent.
   8. Initialize event's type attribute to "payerdetailchange".
   9. Dispatch event at response.
   10. If event.[[waitForUpdate]] is true, disable any part of the user interface that could cause another change to the payer details to be fired.
   11. Otherwise, set event.[[waitForUpdate]] to true.

18.7 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. The user agent SHOULD ensure that this never occurs.
5. Let isRetry be true if request.[[response]] is not null, false otherwise.
6. Let response be request.[[response]] if isRetry is true, or a new PaymentResponse otherwise.
7. If isRetry if false, initialize the newly created response:
   1. Set response.[[request]] to request.
   2. Set response.[[retryPromise]] to null.
   3. Set response.[[complete]] to false.
   4. Set the requestId attribute value of response to the value of request.[[details]].id.
   5. Set request.[[response]] to response.
8. Let handler be the payment handler selected by the user.
9. Set the methodName attribute value of response to the payment method identifier of handler.
10. Set the details attribute value of response to an object resulting from running the handler's steps to respond to a payment request.
11. If the requestShipping value of request.[[options]] is false, then set the shippingAddress attribute value of response to null. Otherwise:
    1. Let redactList be the empty list.
    2. Let shippingAddress be the result of create a PaymentAddress from user-provided input with redactList.
    3. Set the shippingAddress attribute value of response to shippingAddress.
    4. Set the shippingAddress attribute value of request to shippingAddress.
12. 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.
13. 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.
14. 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.
15. 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].
16. Set request.[[state]] to "closed".
17. If isRetry is true, resolve response.[[retryPromise]] with undefined. Otherwise, resolve request.[[acceptPromise]] with response.

18.8 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 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.
3. Set request.[[state]] to "closed".
4. Set request's payment-relevant browsing context's payment request is showing boolean to false.
5. Let error be an "AbortError" DOMException.
6. Let response be request.[[response]].
7. If response is not null:
   1. Set response.[[complete]] to true.
   2. Assert: response.[[retryPromise]] is not null.
   3. Reject response.[[retryPromise]] with error.
8. Otherwise, reject request.[[acceptPromise]] with error.
9. Abort the current user interaction and close down any remaining user interface.

18.9 Update a PaymentRequest's details algorithm

The update a PaymentRequest's details algorithm takes a PaymentDetailsUpdate detailsPromise, a PaymentRequest request, and pmi that is either a DOMString or null (a payment method identifier). The steps are conditional on the detailsPromise settling. If detailsPromise never settles then the payment request is blocked. The user agent SHOULD provide the user with a means to abort a payment request. Implementations MAY choose to implement a timeout for pending updates if detailsPromise doesn't settle in a reasonable amount of time.

In the case where a timeout occurs, or the user manually aborts, or the payment handler decides to abort this particular payment, the user agent MUST run the user aborts the payment request algorithm.

1. Set request.[[updating]] to true.
2. In parallel, disable the user interface that allows the user to accept the payment request. This is to ensure that the payment is not accepted until the user interface is updated with any new details.
3. Upon rejection of detailsPromise:
   1. Abort the update with request and an "AbortError" DOMException.
4. Upon fulfillment of detailsPromise with value value:
   1. Let details be the result of converting value to a PaymentDetailsUpdate dictionary. If this throw an exception, abort the update with request and with the thrown exception.
   2. Let serializedModifierData be an empty list.
   3. Let selectedShippingOption be null.
   4. Let shippingOptions be an empty sequence<PaymentShippingOption>.
   5. Validate and canonicalize the details:
      1. If the total member of details is present, then:
         1. Check and canonicalize total amount details.total.amount. If an exception is thrown, then abort the update with request and that exception.
      2. If the displayItems member of details is present, then for each item in details.displayItems:
         1. Check and canonicalize amount item.amount. If an exception is thrown, then abort the update with request and that exception.
      3. If the shippingOptions member of details is present, and request.[[options]].requestShipping is true, then:
         1. Let seenIDs be an empty set.
         2. For each option in details.shippingOptions:
            1. Check and canonicalize amount option.amount. If an exception is thrown, then abort the update with request and that exception.
            2. If seenIDs[option.id] exists, then abort the update with request and a TypeError.
            3. Append option.id to seenIDs.
            4. Append option to shippingOptions.
            5. If option.selected is true, then set selectedShippingOption to option.id.
      4. If the modifiers member of details is present, then:
         1. Let modifiers be the sequence details.modifiers.
         2. Let serializedModifierData be an empty list.
         3. For each PaymentDetailsModifier modifier in modifiers:
            1. Run the steps to validate a payment method identifier with modifier.supportedMethods. If it returns false, then abort the update with request and a "RangeError" exception. Optionally, inform the developer that the payment method identifier is invalid.
            2. If the total member of modifier is present, then:
               1. Check and canonicalize total amount modifier.total.amount. If an exception is thrown, then abort the update with request and that exception.
            3. If the additionalDisplayItems member of modifier is present, then for each PaymentItem item in modifier.additionalDisplayItems:
               1. Check and canonicalize amount item.amount. If an exception is thrown, then abort the update with request and that exception.
            4. 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. If JSON-serializing throws an exception, then abort the update with request and that exception.
            5. Add serializedData to serializedModifierData.
            6. Remove the data member of modifier, if it is present.
   6. If the paymentMethodErrors member is present and identifier is not null:
      1. If required by the specification that defines the pmi, then convert paymentMethodErrors to an IDL value.
      2. If conversion results in a exception error, abort the update with error.
      3. The payment handler SHOULD display an error for each relevant erroneous field of paymentMethodErrors.
   7. Update the PaymentRequest using the new details:
      1. If the total member of details is present, then:
         1. Set request.[[details]].total to details.total.
      2. If the displayItems member of details is present, then:
         1. Set request.[[details]].displayItems to details.displayItems.
      3. If the shippingOptions member of details is present, and request.[[options]].requestShipping is true, then:
         1. Set request.[[details]].shippingOptions to shippingOptions.
         2. Set the value of request's shippingOption attribute to selectedShippingOption.
      4. If the modifiers member of details is present, then:
         1. Set request.[[details]].modifiers to details.modifiers.
         2. Set request.[[serializedModifierData]] to serializedModifierData.

      5. If request.[[options]].requestShipping is true, and request.[[details]].shippingOptions is empty, then the developer has signified that there are no valid shipping options for the currently-chosen shipping address (given by request's shippingAddress).

         In this case, the user agent SHOULD display an error indicating this, and MAY indicate that the currently-chosen shipping address is invalid in some way. The user agent SHOULD use the error member of details, if it is present, to give more information about why there are no valid shipping options for that address.

         Further, if details["shippingAddressErrors"] member is present, the user agent SHOULD display an error specifically for each erroneous field of the shipping address. This is done by matching each present member of the AddressErrors to a corresponding input field in the shown user interface.

         Similarly, if details["payerErrors"] member is present and request.[[options]]'s requestPayerName, requestPayerEmail, or requestPayerPhone is true, then display an error specifically for each erroneous field.

         Likewise, if details["paymentMethodErrors"] is present, then display errors specifically for each erroneous input field for the particular payment method.

5. Set request.[[updating]] to false.
6. Update the user interface based on any changed values in request. Re-enable user interface elements disabled prior to running this algorithm.

18.10 Validate merchant's details algorithm

The validate merchant's details algorithm takes a Promise opaqueDataPromise and a PaymentRequest request. The steps are conditional on the opaqueDataPromise settling. If opaqueDataPromise never settles then the payment request is blocked. The user agent SHOULD provide the user with a means to abort a payment request. Implementations MAY choose to implement a timeout for pending updates if opaqueDataPromise doesn't settle in a reasonable amount of time. If an implementation chooses to implement a timeout, they MUST execute the steps listed below in the "upon rejection" path. Such a timeout is a fatal error for the payment request.

1. Set request.[[updating]] to true.
2. In parallel, disable the user interface that allows the user to accept the payment request. This is to ensure that the payment is not accepted until the user interface is updated with any new details.
3. Upon rejection of opaqueDataPromise:
   1. Abort the update with request and an "AbortError" DOMException.
4. Upon fulfillment of opaqueDataPromise with value opaqueData:
   1. Validate the merchant using opaqueData.
   2. If opaqueData is invalid, as per the validation rules of the payment handler, abort the update with request and an appropriate exception and return.
   3. Otherwise, set request.[[updating]] to false.
   4. Enable the user interface, allowing the request for payment to proceed.

19.6 Data usage

Payment method owners establish the privacy policies for how user data collected for the payment method may be used. Payment Request API sets a clear expectation that data will be used for the purposes of completing a transaction, and user experiences associated with this API convey that intention. It is the responsibility of the payee to ensure that any data usage conforms to payment method policies. For any permitted usage beyond completion of the transaction, the payee should clearly communicate that usage to the user.

19.7 Exposing user information

The user agent MUST NOT share information about the user with a developer (e.g., the shipping address) without user consent.

The user agent MUST NOT share the values of the displayItems member or additionalDisplayItems member with a third-party payment handler without user consent.

The PaymentMethodChangeEvent enables the payee to update the displayed total based on information specific to a selected payment method. For example, the billing address associated with a selected payment method might affect the tax computation (e.g., VAT), and it is desirable that the user interface accurately display the total before the payer completes the transaction. At the same time, it is desirable to share as little information as possible prior to completion of the payment. Therefore, when a payment method defines the steps for when a user changes payment method, it is important to minimize the data shared via the PaymentMethodChangeEvent's methodDetails attribute. Requirements and approaches for minimizing shared data are likely to vary by payment method and might include:

• Use of a "redactList" for physical addresses. The current specification makes use of a "redactList" to redact the address line, organization, phone number, and recipient from a shippingAddress.
• Support for instructions from the payee identifying specific elements to exclude or include from the payment method response data (returned through PaymentResponse.details). The payee might provide these instructions via PaymentMethodData.data, enabling a payment method definition to evolve without requiring changes to the current API.

Where sharing of privacy-sensitive information might not be obvious to users (e.g., when changing payment methods), it is RECOMMENDED that user agents inform the user of exactly what information is being shared with a merchant.

19.9 canMakePayment() protections

The canMakePayment() methods have the potential to expose user information that could be abused for fingerprinting purposes. User agents are expected to protect the user from abuse of the method. For example, user agents can reduce user fingerprinting by:

• Allowing the user to configure the user agent to turn off canMakePayment(), which would return a promise rejected with a "NotAllowedError" DOMException.
• Rate-limiting the frequency of calls with different parameters.

For rate-limiting the user agent might look at repeated calls from:

• the same effective top-level domain plus one (eTLD+1).
• the top-level browsing context. Alternatively, the user agent may block access to the API entirely for origins know to be bad actors.
• the origin of an iframe or popup window.

These rate-limiting techniques intend to increase the cost associated with repeated calls, whether it is the cost of managing multiple eTLDs or the user experience friction of opening multiple windows (tabs or pop-ups).