Abstract

This specification describes a web API to allow merchants (i.e. web sites selling physical or digital goods) to easily accept payments from different payment methods with minimal integration. User agents (e.g. browsers) will facilitate the payment flow between merchant and user.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

The working group maintains a list of all bug reports that the group has not yet addressed. This draft highlights some of the pending issues that are still to be discussed in the working group. No decision has been taken on the outcome of these issues including whether they are valid. Pull requests with proposed specification text for outstanding issues are strongly encouraged.

This specification was derived from a report published previously by the Web Platform Incubator Community Group.

This document was published by the Web Payments Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-payments-wg@w3.org (subscribe, archives). All comments are welcome.

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 September 2015 W3C Process Document.

1. Introduction

This section is non-normative.

Buying things on the web, particularly on mobile, can be a frustrating experience for users. Every web site has its own flow and its own validation rules, and most require users to manually type in the same set of information over and over again. Likewise, it is difficult and time consuming for developers to create good checkout flows that support various payment schemes.

This specification describes an API that allows user agents (e.g. browsers) to act as an intermediary between the three key parties in every transaction: the merchant (e.g. an online web store), the buyer (e.g. the user buying from the online web store), and the Payment Method (e.g. credit card). Information necessary to process and confirm a transaction is passed between the Payment Method and the merchant via the user agent with the buyer confirming and authorizing as necessary across the flow.

In addition to better, more consistent user experiences, this also enables web sites to take advantage of more secure payment schemes (e.g. tokenization and system-level authentication) that are not possible with standard JavaScript libraries. This has the potential to reduce liability for the merchant and helps protect sensitive user information.

The API described in this document forms part of the Payment Request system described in the Payment Request Architecture [PAYMENTARCH] document.

1.1 Goals

1.2 Non-goals

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, and SHOULD 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 [PAYMENTARCH].
Payment Method Identifiers
The term Payment Method Identifier is defined by the Payment Method Identifiers specification [METHODIDENTIFIERS].
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:

TypeMessage (optional)
InvalidStateErrorThe object is in an invalid state
NotSupportedErrorThe payment method was not supported
SecurityErrorThe 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.
Secure Contexts
The term secure context is defined by the Secure Contexts specification [POWERFUL-FEATURES].

4. PaymentRequest interface

[Constructor(sequence<DOMString> supportedMethods, PaymentDetails details, optional PaymentOptions options, optional object data)]
interface PaymentRequest : EventTarget {
    Promise<PaymentResponse> show();
    void                     abort();

    readonly attribute ShippingAddress? 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 following example shows how to construct a PaymentRequest and begin the user interaction:

Example 1
var payment = new PaymentRequest(supportedMethods, details, options, data);
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(true);
}).catch(function(err) {
  console.error("Uh oh, something bad happened", err.message);
});

4.1 PaymentRequest constructor

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

Issue 40: How does a website pass additional (not payment method specific) data to the payment app?
It is proposed that a conformance criteria for implementations of this API be that any data passed into the request is passed on to the payment app unaltered. This would allow extensions of the data schema such as the addition of properties that are not documented in this specification or known to implementors such as JSON-LD @context or similar to be passed between the website and payment app.
Note

The supportedMethods sequence contains the payment method identifiers for the payment methods that the merchant web site accepts.

Example 2
["visa", "bitcoin", "bobpay.com"]

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
{
  "items": [
    {
      "id": "basket",
      "label": "Sub-total",
      "amount": { "currency": "USD", "value" : "55.00" }, // US$55.00
    },
    {
      "id": "tax",
      "label": "Sales Tax",
      "amount": { "currency": "USD", "value" : "5.00" }, // US$5.00
    },
    {
      "id": "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
}

data is a JSON-serializable object that provides optional information that might be needed by the supported payment methods.

Example 5
{
  "bobpay.com": {
      "merchantIdentifier": "XXXX",
      "bobPaySpecificField": true
  },
  "bitcoin": {
      "address": "XXXX"
  }
}
Issue 15: Combine API parameters into a single request object + options
There is an open issue about whether supportedMethods, details, and data should be combined into a single object.
Issue 16: Use navigator.payments singleton, factory method, or PaymentRequest constructor
There is an open issue about how a payment request is initiated. The options proposed include using a singleton at navigator.payments, using a factory method to create an instance, or using a constructor as currently described in the specification.
Issue 47: Should a payment request be just data, or a programmable object?
There is an open issue about whether the payment request should be a programmable object or should be just pure data that can be operated on by methods.
Issue 19: Should the API handle pre-auth, recurring payments, and similar scenarios
There is an open issue about whether the API should handle occasions when a site wants to request a payment method but not actually make a charge immediately. These may include identification validation, pre-auth for a deposit, pre-auth for a later payment, making recurring payments, and more.
Issue 23: Can the merchant influence order of presentation of payment apps to the user
There is an open issue about whether the merchant can influence order of presentation of payment apps to the user. There is a suggestion that we should support merchants specifying a preference and allow users to express a preference that overrides merchant preferences.
Issue 48: Should list of accepted payment methods be strings or objects?
There is an open issue about whether the list of supported payment methods should be passed to the user agent as a simple sequence of strings or as a more complex and flexible object structure.
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:

  1. If the length of the supportedMethods sequence is zero, then throw a TypeError.
  2. If the global object of the script calling the constructor is not considered a secure context, then throw a SecurityError.
    Issue 22: Spec should use [SecureContext] once that is defined in Web IDL
    Using [SecureContext] in Web IDL will allow us to eliminate this prose.
  3. 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.

  4. If details does not contain a sequence of items with length greater than zero, then throw a TypeError.
  5. If data is not a JSON-serializable object, then throw a TypeError.
  6. If the name of any top level field of data does not match one of the payment method identifiers in supportedMethods, then throw a TypeError.
  7. If the value of any top level field is not a JSON-serializable object, then throw a TypeError.
  8. Let request be a new PaymentRequest.
  9. Store supportedMethods into request@[[supportedMethods]].
  10. Store details into request@[[details]].
  11. Store options into request@[[options]].
  12. Store data into request@[[data]].
  13. Set the value request@[[state]] to created.
  14. Set the value of the shippingAddress attribute on request to null.
  15. Set the value of the shippingOption attribute on request to null.
  16. If details contains a shippingOptions sequence with a length of 1, then set shippingOption to the id of the only ShippingOption in the sequence.
  17. Set the value request@[[updating]] to false.
  18. 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.

Issue 56: Should a website be able to provide a label for the 'Buy' or 'Checkout' button displayed in the payment app?

It may help users understand what they are accepting if the web site is able to label the "accept" button. For example, if a user is about to "Buy" something, "Reserve" something, "Subscribe" to something, etc. That said, this may create payment interface/experience issues and accidentally lead to customers thinking they're performing actions like a one-time purchase, when they are in fact signing up for a subscription.

The show method MUST act as follows:

  1. Let request be the PaymentRequest object on which the method is called..
  2. If the value of request@[[state]] is not created then throw an InvalidStateError.
  3. Set the value of request@[[state]] to interactive.
  4. Let acceptPromise be a new Promise.
  5. Store acceptPromise in request@[[acceptPromise]].
  6. Return acceptPromise and asynchronously perform the remaining steps.
  7. Let acceptedMethods be the sequence of payment method identifiers request@[[supportedMethods]] with all identifiers removed that the user agent does not accept.
  8. If the length of acceptedMethods is zero, then reject acceptPromise with a NotSupportedError.
  9. 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 abort the payment request after the show method has been called and before the [[acceptPromise]] has been resolved.

The abort method MUST act as follows:

  1. If the value of [[state]] is not interactive then throw an InvalidStateError.
  2. Set the value of the internal slot [[state]] to closed.
  3. Return from the method and asynchronously perform the remaining steps.
  4. Abort the current user interaction and close down any remaining user interface

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 SlotDescription (non-normative)
[[supportedMethods]] The supportMethods 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.
[[data]] The payment method specific data supplied to the constructor used by a Payment App to influence the app's behavior.
[[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. CurrencyAmount

dictionary CurrencyAmount {
    required DOMString currency;
    required DOMString value;
};
Issue 119: Should negative amounts be reflected using signed values?
The resolution of the WG per Issue #57 defined a format for currencies and amounts that lacked support for negative values. The format below adds this capability in a way that is not common for financial messaging standards (using signed numbers). The rationale for negative numbers is to support discounts. The group is still discussing whether functionality to support discounts might be implemented in a different manner (e.g., via a transaction type).

A CurrencyAmount dictionary is used to supply monetary amounts. The following fields MUST be supplied for a CurrencyAmount 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 and user agents MUST not attempt to validate this string.
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 6
{
  "currency": "USD",
  "value" : "55.00"
}

6. PaymentDetails dictionary

dictionary PaymentDetails {
    sequence<PaymentItem>    items;
    sequence<ShippingOption> shippingOptions;
};

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:

items
This sequence of PaymentItem dictionaries indicates what the payment request is for. The sequence must contain at least one PaymentItem. The last PaymentItem in the sequence represents the total amount of the payment request. It is the responsibility of the calling code to ensure that the total amount is the sum of the preceding items. The user agent MAY not validate that this is true.
shippingOptions
A sequence containing the different shipping options that the use may choose from.

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

If the sequence only contains one item, then this is the shipping option that will be used and shippingOption will be set to the id of this option without running the shipping option changed algorithm.

Issue 18: Constructor should not include "total" in list of items
There is an open issue about whether the items sequence should special-case the last item in the sequence to represent the total.

7. PaymentOptions dictionary

dictionary PaymentOptions {
    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:

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. If this value is not supplied then the the PaymentRequest behaves as if a value of false had been supplied.

8. PaymentItem dictionary

dictionary PaymentItem {
    required DOMString      id;
    required DOMString      label;
    required CurrencyAmount 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:

id
This is a string identifier used to reference this PaymentItem. It MUST be unique for a given PaymentRequest.
label
This is a human-readable description of the item. The user agent may display this to the user.
amount
A CurrencyAmount 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.
Issue 14: Handling non-decimal currencies
There is an open issue about whether and how to handle non-decimal currencies.

9. ShippingAddress interface

interface ShippingAddress {
    // [...] fields TBC 
};

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 object with the user's selected shipping address.

Issue 6: Write-up proposal for shipping address fields
The fields of the ShippingAddress interface are yet to be defined.
Issue 1: Should the merchant be able to request your email and recipient phone number
There is an open question about what data beyond shipping address the merchant might be able to request from the user agent. Is capturing email and recipient phone important to you?

10. ShippingOption interface

dictionary ShippingOption {
    required string         id;
    required string         label;
    required CurrencyAmount amount;
};

The ShippingOption 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 ShippingOption. 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 CurrencyAmount containing the monetary amount for the item.

11. PaymentResponse interface

interface PaymentResponse {
    readonly attribute DOMString methodName;
    readonly attribute object    details;

    Promise<void> complete(boolean success);
};

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.

11.1 complete()

The complete method must be called after the user has accepted the payment request and the [[acceptPromise]] has been resolved. The complete method takes a boolean argument that indicates the payment was successfully processed if true and that processing failed if false. Calling the complete method tells the user agent that the user interaction is over (and should cause any remaining user interface to be closed).

Issue 17: complete() should take a string argument not boolean
There is an open issue about what values can be supplied to complete. These may depend on the payment method selected and should then be defined in Payment Transaction Message specifications such as the Basic Card Payment document.

The complete method MUST act as follows:

  1. Let promise be a new Promise.
  2. If the value of the internal slot [[completeCalled]] is true, then throw an InvalidStateError.
  3. Set the value of the internal slot [[completeCalled]] to true.
  4. Return promise and asynchronously perform the remaining steps.
  5. Pass the value of success to the Payment App that accepted the payment request.
  6. Close down any remaining user interface.
  7. 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.

11.2 Internal Slots

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

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

12. Events

12.1 Summary

This section is non-normative.

Event nameInterfaceDispatched when...
shippingaddresschange PaymentRequestUpdateEvent The user provides a new shipping address.
shippingoptionchange PaymentRequestUpdateEvent The user chooses a new shipping option.

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

The updateWith method MUST act as follows:

  1. Let target be the PaymentRequest object that is the target of the event.
  2. If the dispatch flag is unset, then throw an InvalidStateError.
  3. If [[waitForUpdate]] is true, then throw an InvalidStateError.
  4. If target@[[state]] is not interactive, then throw an InvalidStateError.
  5. If target@[[updating]] is true, then throw an InvalidStateError.
  6. Set the stop propagation flag and stop immediate propagation flag.
  7. Set [[waitForUpdate]] to true.
  8. Set target@[[updating]] to true.
  9. 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.
  10. Return from the method and asynchronously perform the remaining steps.
  11. Wait until d settles.
  12. If d is resolved with details and details is a PaymentDetails dictionary, then:
    1. If details contains an items value, then copy this value to the items field of target@[[details]].
    2. If details contains a shippingOptions sequence, then copy this value to the shippingOptions field of target@[[details]].
    3. Let newOption be null.
    4. If details contains a shippingOptions sequence with a length of 1, then set newOption to the id of the only ShippingOption in the sequence.
    5. Set the value of shippingOption on target to newOption.
  13. Set [[waitForUpdate]] to false.
  14. Set target@[[updating]] to false.
  15. 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.
Issue 53: Add section on internationalization

The spec needs to clearly state how it will handle internationalization issues (such as selection order for language via explicit preferences, Accept-Language headers, etc.)

Issue 55: Add section on security considerations

The spec should indicate how data might be passed securely through the API using mechanisms such as field level encryption and message signing. While these may not be standardised a reference to the payment method specifications would be appropriate as well as some examples of how those specifcations might implement secure messaging.

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

13.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:

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

13.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:

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

13.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:

  1. If the request@[[updating]] is true, then terminate this algorithm and take no further action. Only one update may take place at a time. This should never occur.
  2. If the request@[[state]] is not set to interactive, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
  3. Let event be a new PaymentRequestUpdateEvent.
  4. Queue a task to fire an event named name of type event at request.

13.4 User agent delegates payment request algorithm

The PaymentRequest interface allows a web page to call abort to tell the user agent to abort the payment request and to tear down any user interface that might be shown. For example, a web page may choose to do this 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 may not always be able to abort a request. For example, if the user agent has delegated responsibility for the request to another app. To support this situation, the user agent must run the User agent delegates payment request algorithm. The algorithm MUST run 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 the request@[[state]] is not interactive, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
  4. Set request@[[state]] to delegated.
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 7: Should we support a delegated state for PaymentRequest?

We believe there are user agent configurations that can cause the UI to get into a state where cancellation by the web page during user interaction is difficult. Users should still be able to cancel the payment but script will not be able to. We need to investigate in more detail the consequences of this and whether it is really needed.

If we specify delegated then it isn't necessary for all user agents to be able to move to this state but it would be necessary for all payment flows that wish to call abort to account for the situation where this may fail in the delegated state.

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.

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

  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 and the not delegated, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
  4. If the requestShipping value of request@[[options]] is true, then if the shippingAddress attribute of request is null or if the shippingOption attribute of request is null, then terminate this algorithm and take no further action. This should never occur.
  5. Let response be a new PaymentResponse.
  6. Set the methodName attribute value of response to the payment method identifier for the payment method that the user selected to accept the payment.
  7. 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.
  8. Set response@[[completeCalled]] to false.
  9. Set request@[[state]] to closed.
  10. Resolve the pending promise request@[[acceptPromise]].
Issue 20: Ensure references are up-to-date
The references in the spec need to be up-to-date.

A. References

A.1 Normative references

[DOM4]
Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C. W3C DOM4. 19 November 2015. W3C Recommendation. URL: http://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: http://www.w3.org/TR/html5/
[ISO4217]
ISO 4217: Codes for the representation of currencies and funds. ISO.
[METHODIDENTIFIERS]
Adrian Bateman; Zach Koch; Richard Barnes. Payment Method Identifiers. W3C Editor's Draft. URL: method-identifiers.html
[POWERFUL-FEATURES]
Mike West; Yan Zhu. W3C. Privileged Contexts. 24 April 2015. W3C Working Draft. URL: http://www.w3.org/TR/powerful-features/
[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: http://www.w3.org/TR/WebIDL-1/

A.2 Informative references

[PAYMENTARCH]
Adrian Bateman; Zach Koch; Richard Barnes. Payment Request Architecture. W3C Editor's Draft. URL: architecture.html