Payment Request API

1.1 Goals

Allow the user agent to act as intermediary between merchants, users, and payment methods
Standardize (to the extent that it makes sense) the communication flow between a merchant, user agent, and payment method
Allow payment methods to bring more secure payment transactions to the web

1.2 Non-goals

Not trying to create a new payment method
Not trying to integrate directly with payment processors

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].

This specification defines one class of products:

Conforming user agent

A user agent MUST behave as described in this specification in order to be considered conformant. In this specification, user agent means a Web browser or other interactive user agent as defined in [HTML5].

User agents MAY implement algorithms given in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms.

A conforming Payment Request API user agent MUST also be a conforming implementation of the IDL fragments of this specification, as described in the “Web IDL” specification. [WEBIDL]

Note

3. Dependencies

This specification relies on several other underlying specifications.

Payment Request Architecture

The terms Payment Method, Payment App, and Payment Transaction Message Specification are defined by the Payment Request Architecture document [ PAYMENT-ARCH].

Payment Method Identifiers

The term Payment Method Identifier is defined by the Payment Method Identifiers specification [ METHOD-IDENTIFIERS].

HTML5

The terms global object, queue a task, browsing context, and top-level browsing context are defined by [HTML5].

ECMA-262 6th Edition, The ECMAScript 2015 Language Specification

The terms Promise, internal slot, TypeError, JSON.stringify, and JSON.parse are defined by [ECMA-262-2015].

This document uses the format object@[[slotname]] to mean the internal slot [[slotname]] of the object object.

The term JSON-serializable object used in this specification means an object that can be serialized to a string using JSON.stringify and later deserialized back to an object using JSON.parse with no loss of data.

DOM4

The Event type and the terms fire an event, dispatch flag, stop propagation flag, and stop immediate propagation flag are defined by [DOM4].

DOMException and the following DOMException types from [DOM4] are used:

Type	Message (optional)
`AbortError`	The payment request was aborted
`InvalidStateError`	The object is in an invalid state
`NotSupportedError`	The payment method was not supported
`SecurityError`	The operation is only supported in a secure context

WebIDL

When this specification says to throw an error, the user agent must throw an error as described in [WEBIDL]. When this occurs in a sub-algorithm, this results in termination of execution of the sub-algorithm and all ancestor algorithms until one is reached that explicitly describes procedures for catching exceptions.

The term extended attribute is defined by [WEBIDL].

Secure Contexts

The term secure context is defined by the Secure Contexts specification [ POWERFUL-FEATURES].

4. PaymentRequest interface

[Constructor(sequence<PaymentMethodData> methodData, PaymentDetails details, optional PaymentOptions options),
 SecureContext]
interface PaymentRequest : EventTarget {
    Promise<PaymentResponse> show();
    Promise<void>            abort();

    readonly attribute PaymentAddress? shippingAddress;
    readonly attribute DOMString?      shippingOption;

    // Supports "shippingaddresschange" event 
             attribute EventHandler    onshippingaddresschange;

    // Supports "shippingoptionchange" event 
             attribute EventHandler    onshippingoptionchange;
};

A web page creates a PaymentRequest to make a payment request. This is typically associated with the user initiating a payment process (e.g., selecting a "Power Up" in an interactive game, pulling up to an automated kiosk in a parking structure, or activating a "Buy", "Purchase", or "Checkout" button). The PaymentRequest allows the web page to exchange information with the user agent while the user is providing input before approving or denying a payment request.

The shippingAddress and shippingOption attributes are populated during processing if the requestShipping flag is set.

Note

The [SecureContext] extended attribute means that the PaymentRequest is only exposed within a secure context and won't be accessible elsewhere.

The following example shows how to construct a PaymentRequest and begin the user interaction:

Example 1

var payment = new PaymentRequest(methodData, details, options);
payment.addEventListener("shippingaddresschange", function (changeEvent) {
    // Process shipping address change
});

payment.show().then(function(paymentResponse) {
  // Process paymentResponse
  // paymentResponse.methodName contains the selected payment method
  // paymentResponse.details contains a payment method specific response
  paymentResponse.complete("success");
}).catch(function(err) {
  console.error("Uh oh, something bad happened", err.message);
});

4.1 PaymentRequest constructor

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

Note

The methodData sequence contains PaymentMethodData dictionaries containing the payment method identifiers for the payment methods that the web site accepts and any associated payment method specific data.

Example 2

[
  {
    supportedMethods: ["visa","bitcoin"]
  },
  {
    supportedMethods: ["bobpay.com"],
    data: {
      merchantIdentifier: "XXXX",
      bobPaySpecificField: true
    }
  }
]

The details object contains information about the transaction that the user is being asked to complete such as the line items in an order.

Example 3

{
  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
  }
}

The options object contains information about what options the web page wishes to use from the payment request system.

Example 4

{
  requestShipping: true
}

Issue 15: Combine API parameters into a single request object + options

There is an open issue about whether methodData, details, and data should be combined into a single object.

Issue 51: Should the payment API be more conversational or less conversational?

There is an open issue regarding whether the current pattern of using events for exchange of data between the user agent and the website is the best design for this API. An alternative pattern has been proposed in the issue thread.

The PaymentRequest constructor MUST act as follows:

If the length of the methodData sequence is zero, then throw a TypeError.
For each PaymentMethodData dictionary, if the length of the supportedMethods sequence is zero, then throw a TypeError.
If the browsing context of the script calling the constructor is not a top-level browsing context, then throw a SecurityError.

Issue 2: Should the Payment Request API only be available in a top-level browsing context?

There is an open issue about requiring a top-level browsing context for using PaymentRequest. Requiring one is a mitigation for a user being tricked into thinking a trusted site is asking for payment when in fact an untrusted iframe is asking for payment. The problem is some iframes may have a legitimate reason to request payment.
If details does not contain a value for total, then throw a TypeError.
If the first character of details.total.amount.value is U+002D HYPHEN-MINUS, then throw a TypeError. total MUST be a non-negative amount.
If a payment method identifier appears more than once in the methodData or details.modifiers sequences, then throw a TypeError.
For each PaymentMethodData in methodData, if the data field is supplied but is not a JSON-serializable object, then throw a TypeError.
For each PaymentDetailsModifier in details.modifiers, if the total field is supplied and the first character of total.amount.value is U+002D HYPHEN-MINUS, then throw a TypeError. total MUST be a non-negative amount.
Let request be a new PaymentRequest.
Store methodData into request@[[methodData]].
The methodData supplied to the PaymentRequest constructor SHOULD be in the order of preference of the caller. Implementations MAY show payment methods in this order if possible but SHOULD prioritize the preference of the user when presenting payment methods.
Store details into request@[[details]].
Store options into request@[[options]].
Set the value request@[[state]] to created.
Set the value of the shippingAddress attribute on request to null.
Set the value of the shippingOption attribute on request to null.
If details contains a shippingOptions sequence and if any PaymentShippingOption in the sequence has the selected field set to true, then set shippingOption to the id of the last ShippingOption in the sequence with selected set to true.
Set the value request@[[updating]] to false.
Return request.

4.2 show()

The show method is called when the page wants to begin user interaction for the payment request. The show method will return a Promise that will be resolved when the user accepts the payment request. Some kind of user interface will be presented to the user to facilitate the payment request after the show method returns.

The show method MUST act as follows:

Let request be the PaymentRequest object on which the method is called.
If the value of request@[[state]] is not created then throw an InvalidStateError.
Set the value of request@[[state]] to interactive.
Let acceptPromise be a new Promise.
Store acceptPromise in request@[[acceptPromise]].
Return acceptPromise and asynchronously perform the remaining steps.
Let supportedMethods be the union of all the supportedMethods sequences from each PaymentMethodData in the request@[[methodData]] sequence.
Let acceptedMethods be supportedMethods with all identifiers removed that the user agent does not accept.
If the length of acceptedMethods is zero, then reject acceptPromise with a NotSupportedError.
Show a user interface to allow the user to interact with the payment request process. The acceptPromise will later be resolved by the user accepts the payment request algorithm through interaction with the user interface.

4.3 abort()

The abort method may be called if the web page wishes to tell the user agent to abort the payment request and to tear down any user interface that might be shown. abort can only be called after the show method has been called and before the request@[[acceptPromise]] has been resolved. For example, a web page might choose to do this if the goods they are selling are only available for a limited amount of time. If the user does not accept the payment request within the allowed time period, then the request will be aborted.

A user agent might not always be able to abort a request. For example, if the user agent has delegated responsibility for the request to another app. In this situation, abort will reject the returned Promise.

Issue 39: How are web-based payment apps supported?

The architecture document suggests that payment apps may take numerous forms, including as web-based apps. This specification should describe how the user-agent will pass the payment request data and the complete signal to a web-based payment app and also how it will receive the payment response from the payment app.

Issue 50: How are payment requests and responses passed between the browser and third-party native wallets?

This specification should describe how the user agent will pass the payment request data and the complete signal to a native payment app and also how it will receive the payment response from the payment app.

The abort method MUST act as follows:

Let request be the PaymentRequest object on which the method is called.
If the value of request@[[state]] is not interactive then throw an InvalidStateError.
Let promise be a new Promise.
Return promise and asynchronously perform the remaining steps.
Try to abort the current user interaction and close down any remaining user interface.
If it is not possible to abort the current user interaction, then reject promise with InvalidStateError and abort this algorithm.
Set the value of the internal slot request@[[state]] to closed.
Reject the promise request@[[acceptPromise]] with an AbortError.
Resolve promise with undefined.

4.4 State transitions

The internal slot [[state]] follows the following state transitions:

Transition diagram for internal slot state of a PaymentRequest object

4.5 shippingAddress

shippingAddress 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 is an EventHandler for an Event named shippingaddresschange.

4.6 shippingOption

shippingOption 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 is an EventHandler for an Event named shippingoptionchange.

4.7 Internal Slots

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

Internal Slot	Description (non-normative)
[[methodData]]	The `methodData` supplied to the constructor.
[[details]]	The current `PaymentDetails` for the payment request initially supplied to the constructor and then updated with calls to `updateWith`.
[[options]]	The `PaymentOptions` supplied to the constructor.
[[state]]	The current state of the payment request.
[[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.

5. PaymentMethodData dictionary

dictionary PaymentMethodData {
    required sequence<DOMString> supportedMethods;
             object              data;
};

A PaymentMethodData dictionary is used to indicate a set of supported payment methods and any associated payment method specific data for those methods.

The following fields are part of the PaymentMethodData dictionary:

supportedMethods: supportedMethods is a required sequence of strings containing payment method identifiers for payment methods that the merchant web site accepts.
data: data is a JSON-serializable object that provides optional information that might be needed by the supported payment methods.

6. PaymentCurrencyAmount

dictionary PaymentCurrencyAmount {
    required DOMString currency;
    required DOMString value;
};

A PaymentCurrencyAmount dictionary is used to supply monetary amounts. The following fields MUST be supplied for a PaymentCurrencyAmount to be valid:

currency: currency is a string containing a currency identifier. The most common identifiers are three-letter alphabetic codes as defined by [ISO4217] (for example, "USD" for US Dollars) however any string is considered valid.
value: A string containing the decimal monetary value. If a decimal separator is needed, then the string MUST use a single U+002E FULL STOP character as the decimal separator. The string MUST begin with a single U+002D HYPHEN-MINUS character if the value is negative. All other characters must be characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).

Note

The string should match the regular expression ^-?[0-9]+(\.[0-9]+)?$.

The following example shows how to represent US$55.00.

Example 5

{
  "currency": "USD",
  "value" : "55.00"
}

7. PaymentDetails dictionary

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

The PaymentDetails dictionary is passed to the PaymentRequest constructor and provides information about the requested transaction. The PaymentDetails dictionary is also used to update the payment request using updateWith.

The following fields are part of the PaymentDetails dictionary:

total

This PaymentItem contains the total amount of the payment request.

total MUST be a non-negative value. This means that the total.amount.value field MUST NOT begin with a U+002D HYPHEN-MINUS character.

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.

The user agent MAY validate that the total amount is the sum of these items, but it is the responsibility of the calling code to ensure that.

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 field 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 field is only used if the PaymentRequest was constructed with PaymentOptions requestShipping set to true.

Note

If the sequence has an item with the selected field set to true, then authors SHOULD ensure that the total field 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.

8. PaymentDetailsModifier dictionary

dictionary PaymentDetailsModifier {
    required sequence<DOMString>   supportedMethods;
             PaymentItem           total;
             sequence<PaymentItem> additionalDisplayItems;
};

The PaymentDetailsModifier dictionary provides details that modify the PaymentDetails based on payment method identifier. It contains the following fields:

supportedMethods: The supportedMethods field contains a sequence of payment method identifiers. The remaining fields in the PaymentDetailsModifier apply only if the user selects a payment method included in this sequence.
total: This PaymentItem value overrides the total field in the PaymentDetails dictionary for the payment method identifiers in the supportedMethods field.
additionalDisplayItems: This sequence of PaymentItem dictionaries provides additional display items that are appended to the displayItems field in the PaymentDetails dictionary for the payment method identifiers in the supportedMethods field. This field is commonly used to add a discount or surcharge line item indicating the reason for the different total amount for the selected payment method that the user agent MAY display.
The user agent MAY validate that the total amount is the sum of the displayItems and the additionalDisplayItems, but it is the responsibility of the calling code to ensure that.

9. PaymentOptions dictionary

dictionary PaymentOptions {
    boolean requestPayerEmail = false;
    boolean requestPayerPhone = false;
    boolean requestShipping = false;
};

The PaymentOptions dictionary is passed to the PaymentRequest constructor and provides information about the options desired for the payment request.

The following fields MAY be passed to the PaymentRequest constructor:

requestPayerEmail: This boolean value indicates whether the user agent should collect and return the payer's email address as part of the payment request. For example, this would be set to true to allow a merchant to email a receipt.
requestPayerPhone: This boolean value indicates whether the user agent should collect and return the payer's phone number as part of the payment request. For example, this would be set to true to allow a merchant to phone a customer with a billing enquiry.
requestShipping: This boolean value indicates whether the user agent should collect and return a shipping address as part of the payment request. For example, this would be set to true when physical goods need to be shipped by the merchant to the user. This would be set to false for an online-only electronic purchase transaction.

10. PaymentItem dictionary

dictionary PaymentItem {
    required DOMString             label;
    required PaymentCurrencyAmount amount;
};

A sequence of one or more PaymentItem dictionaries is included in the PaymentDetails dictionary to indicate the what the payment request is for and the value asked for.

The following fields MUST be included in a PaymentItem for it to be valid:

label: This is a human-readable description of the item. The user agent may display this to the user.
amount: A PaymentCurrencyAmount containing the monetary amount for the item.

Issue 3: Should it be possible to provide amounts in more than one currency

There is an open issue about whether it should be possible to provide a PaymentItem with amounts in more than once currency.

Issue 4: Should it be possible to vary amounts depending on payment method

There is an open issue about whether it should be possible to provide a different amounts depending upon the payment method.

11. PaymentAddress interface

interface PaymentAddress {
    readonly attribute DOMString              country;
    readonly attribute FrozenArray<DOMString> addressLine;
    readonly attribute DOMString              region;
    readonly attribute DOMString              city;
    readonly attribute DOMString              dependentLocality;
    readonly attribute DOMString              postalCode;
    readonly attribute DOMString              sortingCode;
    readonly attribute DOMString              languageCode;
    readonly attribute DOMString              organization;
    readonly attribute DOMString              recipient;
    readonly attribute DOMString              careOf;
    readonly attribute DOMString              phone;
};

country: This is the CLDR (Common Locale Data Repository) region code. For example, US, GB, CN, or JP.
addressLine: 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: 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: This is the city/town portion of the address.
dependentLocality: This is the dependent locality or sublocality within a city. For example, used for neighborhoods, boroughs, districts, or UK dependent localities.
postalCode: This is the postal code or ZIP code, also known as PIN code in India.
sortingCode: This is the sorting code as used in, for example, France.
languageCode: This is the BCP-47 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: This is the organization, firm, company, or institution at this address.
recipient: This is the name of the recipient or contact person.
careOf: This is the name of an intermediary party or entity responsible for transferring packages between the postal service and the recipient.
phone: This is the phone number of the recipient or contact person.

If the requestShipping flag was set to true in the PaymentOptions passed to the PaymentRequest constructor, then the user agent will populate the shippingAddress field of the PaymentRequest and ultimately the PaymentResponse object with the user's selected shipping address after the user has accepted the payment.

12. PaymentShippingOption dictionary

dictionary PaymentShippingOption {
    required DOMString             id;
    required DOMString             label;
    required PaymentCurrencyAmount amount;
             boolean               selected = false;
};

The PaymentShippingOption dictionary has fields describing a shipping option. A web page can provide the user with one or more shipping options by calling the updateWith method in response to a change event.

The following fields MUST be included in a PaymentItem for it to be valid:

id: This is a string identifier used to reference this PaymentShippingOption. It MUST be unique for a given PaymentRequest.
label: This is a human-readable description of the item. The user agent SHOULD use this string to display the shipping option to the user.
amount: A PaymentCurrencyAmount containing the monetary amount for the item.
selected: This is set to true to indicate that this is the default selected PaymentShippingOption in a sequence. User agents SHOULD display this option by default in the user interface.

13. PaymentResponse interface

enum PaymentComplete {
    "success",
    "fail",
    ""
};

interface PaymentResponse {
    readonly attribute DOMString       methodName;
    readonly attribute object          details;
    readonly attribute PaymentAddress? shippingAddress;
    readonly attribute DOMString?      shippingOption;
    readonly attribute DOMString?      payerEmail;
    readonly attribute DOMString?      payerPhone;

    Promise<void> complete(optional PaymentComplete result = "");
};

A PaymentResponse is returned when a user has selected a payment method and approved a payment request. It contains the following fields:

methodName: The payment method identifier for the payment method that the user selected to fulfil the transaction.
details: A JSON-serializable 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 app that satisfies the payment request.
shippingAddress: 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: 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.
payerEmail: 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: 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.

13.1 complete()

The complete method must be 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 user interaction is over (and should cause any remaining user interface to be closed).

The complete method takes a string argument from the PaymentComplete enum (result). These values are used to influence the user experience provided by the user agent when the user interface is dismissed. The value of result has the following meaning:

"success": Indicates the payment was successfully processed. The user agent MAY display UI indicating success.
"fail": Indicates that processing of the payment failed. The user agent MAY display UI indicating failure.
"": The web page did not indicate success or failure and the user agent SHOULD NOT display UI indicating success or failure. This is the default value if the web page does not supply a value for result.

The complete method MUST act as follows:

Let promise be a new Promise.
If the value of the internal slot [[completeCalled]] is true, then throw an InvalidStateError.
Set the value of the internal slot [[completeCalled]] to true.
Return promise and asynchronously perform the remaining steps.
Close down any remaining user interface. The user agent MAY use the value result to influence the user experience. User agents SHOULD treat unrecognized result values as the value "".
Resolve promise with undefined.

Issue 5: Should the web page be able to provide status information before calling complete()

There is an open issue about whether there should be a way for a merchant to keep the user informed about the progress of a transaction after the user approves the payment request.

13.2 Internal Slots

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

Internal Slot	Description (non-normative)
[[completeCalled]]	true if the `complete` method has been called and false otherwise.

14. Events

14.1 Summary

This section is non-normative.

Event name	Interface	Dispatched when...
`shippingaddresschange`	`PaymentRequestUpdateEvent`	The user provides a new shipping address.
`shippingoptionchange`	`PaymentRequestUpdateEvent`	The user chooses a new shipping option.

14.2 PaymentRequestUpdateEvent

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

dictionary PaymentRequestUpdateEventInit : EventInit {
};

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

If the web page wishes to update the payment request then it should call updateWith and provide a promise that will resolve with a PaymentDetails dictionary containing changed values that the user agent SHOULD present to the user.

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

14.2.1 updateWith()

The updateWith method MUST act as follows:

Let target be the PaymentRequest object that is the target of the event.
If the dispatch flag is unset, then throw an InvalidStateError.
If [[waitForUpdate]] is true, then throw an InvalidStateError.
If target@[[state]] is not interactive, then throw an InvalidStateError.
If target@[[updating]] is true, then throw an InvalidStateError.
Set the stop propagation flag and stop immediate propagation flag.
Set [[waitForUpdate]] to true.
Set target@[[updating]] to true.
The user agent SHOULD 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 web page has made changes required by the change. The web page MUST settle the promise d to indicate that the payment request is valid again.
The user agent SHOULD disable any part of the user interface that could cause another update event to be fired. Only one update may be processed at a time.

Issue: Consider adding a timeout to the updating flag in case page doesn't resolve promise from updateWith

We should consider adding a timeout mechanism so that if the page never resolves the promise within a reasonable amount of time then the user agent behaves as if the promise was rejected.
Return from the method and asynchronously perform the remaining steps.
Wait until d settles.
If d is rejected, then:
1. Abort the current user interaction and close down any remaining user interface.
2. Set the value of the internal slot target@[[state]] to closed.
3. Reject the promise target@[[acceptPromise]] with an AbortError.
4. Abort this algorithm.
Note

If the promise d is rejected then this is a fatal error for the payment request. This would potentially leave the payment request in an inconsistent state since the web page hasn't successfully handled the change event. Consequently, if d is rejected then the payment request is aborted.
User agents MAY show an error message to the user when this occurs.
If d is resolved with details and details is a PaymentDetails dictionary, then:
1. If details contains a total value and the first character of total.amount.value is NOT U+002D HYPHEN-MINUS, then copy total value to the total field of target@[[details]] (total MUST be a non-negative amount).
2. If details contains a displayItems value, then copy this value to the displayItems field of target@[[details]].
3. If details contains a modifiers value, then copy this value to the modifiers field of target@[[details]].
4. If details contains a shippingOptions sequence, then:
  1. Copy the shippingOptions sequence from details to the shippingOptions field of target@[[details]].
  2. Let newOption be null.
  3. If details contains a shippingOptions sequence and if any ShippingOption in the sequence has the selected field set to true, then set newOption to the id of the last ShippingOption in the sequence with selected set to true.
  4. Set the value of shippingOption on target to newOption.
Set [[waitForUpdate]] to false.
Set target@[[updating]] to false.
The user agent should update the user interface based on any changed values in target. The user agent SHOULD re-enable user interface elements that might have been disabled in the steps above if appropriate.

15. Algorithms

When the internal slot [[state]] of a PaymentRequest object is set to interactive, the user agent will trigger the following algorithms based on user interaction.

15.1 Shipping address changed algorithm

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

Let request be the PaymentRequest object that the user is interacting with.
Let name be shippingaddresschange.
Set the shippingAddress attribute on request to the shipping address provided by the user.
Run the PaymentRequest updated algorithm with request and name.

15.2 Shipping option changed algorithm

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

Let request be the PaymentRequest object that the user is interacting with.
Let name be shippingoptionchange.
Set the shippingOption attribute on request to the id string of the PaymentShippingOption provided by the user.
Run the PaymentRequest updated algorithm with request and name.

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

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.
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.
Let event be a new PaymentRequestUpdateEvent.
Queue a task to fire an event named name of type event at request.

15.4 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 run the following steps:

Let request be the PaymentRequest object that the user is interacting with.
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.
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.
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.
Let response be a new PaymentResponse.
Set the methodName attribute value of response to the payment method identifier for the payment method that the user selected to accept the payment.
Set the details attribute value of response to a JSON-serializable object containing the payment method specific message used by the merchant to process the transaction. The format of this response will be defined by a Payment Transaction Message Specification.
If the requestShipping value of request@[[options]] is true, then copy the shippingAddress attribute of request to the shippingAddress attribute of response.
If the requestShipping value of request@[[options]] is true, then copy the shippingOption attribute of request to the shippingOption attribute of response.
If the requestPayerEmail value of request@[[options]] is true, then set the payerEmail attribute of response to the payer's email address selected by the user.
If the requestPayerPhone value of request@[[options]] is true, then set the payerPhone attribute of response to the payer's phone number selected by the user.
Set response@[[completeCalled]] to false.
Set request@[[state]] to closed.
Resolve the pending promise request@[[acceptPromise]] with response.

16.1 Encryption of data fields

The PaymentRequest API does not directly support encryption of data fields. Individual payment methods may choose to include support for encrypted data but it is not mandatory that all payment methods support this.

17.1 Exposing user information

The user agent should never share information about the user to the web page (such as the shipping address) without user consent.

A.1 Normative references

[DOM4]: Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C. W3C DOM4. 19 November 2015. W3C Recommendation. URL: https://www.w3.org/TR/dom/
[ECMA-262-2015]: Allen Wirfs-Brock. Ecma International. ECMA-262 6th Edition, The ECMAScript 2015 Language Specification. June 2015. Standard. URL: http://www.ecma-international.org/ecma-262/6.0/index.html
[HTML5]: Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. W3C. HTML5. 28 October 2014. W3C Recommendation. URL: https://www.w3.org/TR/html5/
[ISO4217]: ISO 4217: Codes for the representation of currencies and funds. ISO.
[METHOD-IDENTIFIERS]: Adrian Bateman; Zach Koch; Richard Barnes; Roy McElmurry. Payment Method Identifiers. W3C Editor's Draft. URL: https://www.w3.org/TR/payment-method-id/
[POWERFUL-FEATURES]: Mike West. W3C. Secure Contexts. 26 April 2016. W3C Working Draft. URL: https://www.w3.org/TR/secure-contexts/
[RFC2119]: S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]: Cameron McCormack; Boris Zbarsky. W3C. WebIDL Level 1. 8 March 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/WebIDL-1/

A.2 Informative references

[PAYMENT-ARCH]: Adrian Bateman; Zach Koch; Richard Barnes; Roy McElmurry. Payment Request Architecture. W3C Editor's Draft. URL: https://w3c.github.io/browser-payment-api/specs/architecture.html

Abstract

Status of This Document

1. Introduction

1.1 Goals

1.2 Non-goals

2. Conformance

3. Dependencies

4. PaymentRequest interface

4.1 PaymentRequest constructor

4.2 show()

4.3 abort()

4.4 State transitions

4.5 shippingAddress

4.6 shippingOption

4.7 Internal Slots

5. PaymentMethodData dictionary

6. PaymentCurrencyAmount

7. PaymentDetails dictionary

8. PaymentDetailsModifier dictionary

9. PaymentOptions dictionary

10. PaymentItem dictionary

11. PaymentAddress interface

12. PaymentShippingOption dictionary

13. PaymentResponse interface

13.1 complete()

13.2 Internal Slots

14. Events

14.1 Summary

14.2 PaymentRequestUpdateEvent

14.2.1 updateWith()

15. Algorithms

15.1 Shipping address changed algorithm

15.2 Shipping option changed algorithm

15.3 PaymentRequest updated algorithm

15.4 User accepts the payment request algorithm

16. Security Considerations

16.1 Encryption of data fields

17. Privacy Considerations

17.1 Exposing user information

A. References

A.1 Normative references

A.2 Informative references