From 94e40c5db19cd0afdb5f2a79e62468ea80bfa2d7 Mon Sep 17 00:00:00 2001 From: Adrian Hope-Bailie Date: Tue, 31 May 2016 14:29:02 +0200 Subject: [PATCH] Move PMI and Card specs out of repo - Move PaymentRequest API spec to root - Update references - Redirect old URL to new - Move images to images folder --- README.md | 8 +- {specs => images}/state-transitions.svg | 0 index.html | 1382 ++++++++++++++++++++++- specs/basic-card-payment.html | 260 ----- specs/method-identifiers.html | 149 --- specs/paymentrequest.html | 1355 +--------------------- 6 files changed, 1357 insertions(+), 1797 deletions(-) rename {specs => images}/state-transitions.svg (100%) delete mode 100644 specs/basic-card-payment.html delete mode 100644 specs/method-identifiers.html diff --git a/README.md b/README.md index ea5a5007..facd0415 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ +# Web Payments - Payment Request API +## A Payment API for Browsers -# Payment API for Browsers +This repository contains a draft specification from the [W3C Web Payments Working Group](https://www.w3.org/Payments/WG/). -This is the repository contains drafts from the [W3C Web Payments Working Group](https://www.w3.org/Payments/WG/) for a browser API to make payments. - -An index of documents available is at https://w3c.github.io/browser-payment-api/. +The editor's draft is available at: https://w3c.github.io/browser-payment-api/ \ No newline at end of file diff --git a/specs/state-transitions.svg b/images/state-transitions.svg similarity index 100% rename from specs/state-transitions.svg rename to images/state-transitions.svg diff --git a/index.html b/index.html index 027302c5..cea239d4 100644 --- a/index.html +++ b/index.html @@ -1,50 +1,1338 @@ - - - W3C Web Payments Working Group - Browser Payment API Specifications - - - - -
-

W3C Web Payments Working Group

-

Browser Payment API Specifications

-
- -
-

Specifications - Editor's Drafts

-
-
Architecture
-
- The Payment Request architecture is designed to separate different concerns of - the Payment Request system into different specifications so that they can be - discussed and moved forward independently. This document describes the - architecture and explains what different specifications may be created and - how the relate to each other. -
-
Payment Method Identifiers
-
- The PaymentRequest API requires that - merchants supply a list identifiers for supported payment methods. This - document defines those identifier strings and how they are created. -
-
PaymentRequest API
-
- This is a proposal for a new web API that will allow merchants (i.e. websites - selling physical or digital goods) to easily accept payments from multiple - payment methods with minimal integration. -
-
Basic Card Payment
-
- This specification is a Payment Transaction Message Specification used by the - PaymentRequest API to support payment by payment cards such as credit or debit cards. -
-
-
- - - + table { margin-top: 0.75em; border-collapse:collapse; border-style:hidden hidden none hidden } + table thead { border-bottom:solid } + table tbody th:first-child { border-left:solid } + table td, table th { border-left:solid; border-right:solid; border-bottom:solid thin; vertical-align:top; padding:0.2em } + li { margin-top: 0.5em; margin-bottom: 0.5em;} + + + +
+

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

+
+ +
+

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

+
+ +
+

Introduction

+

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 [[PAYMENT-ARCH]] document.

+ +
+

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
    • +
+
+ +
+

Non-goals

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

+ 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]] +

+ + +
+
+
+ +
+

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:

+ + + + + + +
TypeMessage (optional)
AbortErrorThe payment request was aborted
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. +

The term extended attribute is defined by [[!WEBIDL]].

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

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

+ + 
+        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);
+        });
+
+ +
+

PaymentRequest constructor

+

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

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

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.

+ 
+            [
+              {
+                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.

+ 
+            {
+              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.

+ + 
+            {
+              requestShipping: true
+            }
+
+
+ +
+ There is an open issue about whether methodData, details, and data + should be combined into a single object. +
+ +
+ 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. +
+ +
+ 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 methodData sequence is zero, then throw + a TypeError. +
    2. +
  2. + For each PaymentMethodData dictionary, if the length of the + supportedMethods sequence is zero, then throw a TypeError. +
    3. +
  3. + If the browsing context of the script calling the constructor is + not a top-level browsing context, then throw a SecurityError. +
    +

    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. +
  4. + If details does not contain a value for total, then throw a + TypeError. +
    5. +
  5. + 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. +
    6. +
  6. + For each PaymentMethodData in methodData, if the data field + is supplied but is not a JSON-serializable object, then throw a TypeError. +
    7. +
  7. Let request be a new PaymentRequest.
    8. +
  8. + 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. +

    +
    9. +
  9. Store details into request@[[\details]].
    10. +
  10. Store options into request@[[\options]].
    11. +
  11. Set the value request@[[\state]] to created.
    12. +
  12. + Set the value of the shippingAddress attribute on request to null. +
    13. +
  13. + Set the value of the shippingOption attribute on request to null. +
    14. +
  14. + If details contains a shippingOptions sequence with a + length of 1, then set shippingOption to the id of + the only ShippingOption in the sequence. +
    15. +
  15. + If details contains a shippingOptions sequence with a + length greater than 1, and if any ShippingOption 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. +
    16. +
  16. Set the value request@[[\updating]] to false.
    17. +
  17. Return request.
    18. +
+
+ +
+

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

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

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

+ +

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

+ +

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

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

State transitions

+

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

+ Transition diagram for internal slot state of a PaymentRequest object +
+ +
+

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

+
+ +
+

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

+
+ +
+

Internal Slots

+

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Internal SlotDescription (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. +
+
+ +
+ +
+

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

CurrencyAmount

+ 
+dictionary CurrencyAmount {
+  required DOMString currency;
+  required DOMString value;
+};
+
+

+ 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). +
+ The string should match the regular expression ^-?[0-9]+(\.[0-9]+)?$. +
+
+
+ +

The following example shows how to represent US$55.00.

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

PaymentDetails dictionary

+ 
+dictionary PaymentDetails {
+  PaymentItem total;
+  sequence<PaymentItem> displayItems;
+  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: +

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

+

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.

+

+ If the sequence contains only one item or 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. +

+
+
+
+ +
+

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

PaymentItem dictionary

+ 
+        dictionary PaymentItem {
+          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: +

+
+
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. +
+ There is an open issue about whether it should be possible to provide a PaymentItem + with amounts in more than once currency. +
+
+ There is an open issue about whether it should be possible to provide a different amounts depending + upon the payment method. +
+
+
+
+ +
+

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

+
+ 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? +
+
+ +
+

ShippingOption interface

+ 
+        dictionary ShippingOption {
+          required string id;
+          required string label;
+          required CurrencyAmount amount;
+          boolean selected = false;
+        };
+
+

+ 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. +
+
selected
+
This is set to true to indicate that this is the default selected ShippingOption + in a sequence. User agents SHOULD display this option by default in the user interface.
+
+
+ +
+

PaymentResponse interface

+ 
+        enum PaymentComplete { "success", "fail", "" };
+
+        interface PaymentResponse {
+          readonly attribute DOMString methodName;
+          readonly attribute object details;
+          readonly attribute PaymentAddress? shippingAddress;
+          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. +
+
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. +
+
+ +
+

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:

+
    +
  1. Let promise be a new Promise.
    2. +
  2. + If the value of the internal slot [[\completeCalled]] is true, then throw an InvalidStateError. +
    3. +
  3. Set the value of the internal slot [[\completeCalled]] to true.
    4. +
  4. Return promise and asynchronously perform the remaining steps.
    5. +
  5. 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 "".
    6. +
  6. Resolve promise with undefined.
    7. +
+ +
+ 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. +
+
+ +
+

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

Events

+ +
+

Summary

+ + + + + + + + + + + + + +
Event nameInterfaceDispatched when...
shippingaddresschangePaymentRequestUpdateEventThe user provides a new shipping address.
shippingoptionchangePaymentRequestUpdateEventThe user chooses a new shipping option.
+
+ +
+

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. +
  2. If the dispatch flag is unset, then throw an InvalidStateError.
    3. +
  3. + If [[\waitForUpdate]] is true, then throw an InvalidStateError. +
    4. +
  4. + If target@[[\state]] is not interactive, then throw an + InvalidStateError. +
    5. +
  5. + If target@[[\updating]] is true, then throw + an InvalidStateError. +
    6. +
  6. Set the stop propagation flag and stop immediate propagation flag.
    7. +
  7. Set [[\waitForUpdate]] to true.
    8. +
  8. Set target@[[\updating]] to true.
    9. +
  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.

    +
    + 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. +
  10. Return from the method and asynchronously perform the remaining steps.
    11. +
  11. Wait until d settles.
    12. +
  12. 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. +
    2. + If details contains a displayItems value, then copy + this value to the displayItems field of target@[[\details]]. +
      3. +
    3. + If details contains a shippingOptions sequence, then: +
        +
      1. + Copy the shippingOptions sequence from details to the + shippingOptions field of target@[[\details]]. +
        2. +
      2. Let newOption be null.
        3. +
      3. + If details contains a shippingOptions sequence with a + length of 1, then set newOption to the id of the only + ShippingOption in the sequence. +
        4. +
      4. + If details contains a shippingOptions sequence with a + length greater than 1, 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. +
        5. +
      5. + Set the value of shippingOption on target to + newOption. +
        6. +
      +
      4. +
    +
    13. +
  13. Set [[\waitForUpdate]] to false.
    14. +
  14. Set target@[[\updating]] to false.
    15. +
  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. +
    16. +
+ +
+
+ +

+ 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.) +

+ +
+

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.

+ +
+

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. +
  2. Let name be shippingaddresschange.
    3. +
  3. + Set the shippingAddress attribute on request to the + shipping address provided by the user. +
    4. +
  4. + Run the PaymentRequest updated algorithm with request and name. +
    5. +
+
+ +
+

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. +
  2. Let name be shippingoptionchange.
    3. +
  3. + Set the shippingOption attribute on request to the + id string of the ShippingOption provided by the user. +
    4. +
  4. + Run the PaymentRequest updated algorithm with request and name. +
    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.

+

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. +
  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. +
  3. Let event be a new PaymentRequestUpdateEvent.
    4. +
  4. + Queue a task to fire an event named name of type event + at request. +
    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. +
  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. +
  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. +
  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. +
  5. + Let response be a new PaymentResponse. +
    6. +
  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. +
  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. +
  8. + If the requestShipping value of request@[[\options]] + is true, then copy the shippingAddress attribute of + request to the shippingAddress attribute of response. +
    9. +
  9. + 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. +
    10. +
  10. + 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. +
    11. +
  11. + Set response@[[\completeCalled]] to false. +
    12. +
  12. + Set request@[[\state]] to closed. +
    13. +
  13. + Resolve the pending promise request@[[\acceptPromise]] with response. +
    14. +
+
+
+ +
+

Security Considerations

+

+ This section is a placeholder to record security considerations as we gather them through working + group discussion. +

+
+

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

+
+
+ +
+

Privacy Considerations

+

+ This section is a placeholder to record privacy considerations as we gather them through working + group discussion. +

+
+

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

+
+
+ +
+
+ The references in the spec need to be up-to-date. +
+ + + \ No newline at end of file diff --git a/specs/basic-card-payment.html b/specs/basic-card-payment.html deleted file mode 100644 index 74ba4673..00000000 --- a/specs/basic-card-payment.html +++ /dev/null @@ -1,260 +0,0 @@ - - - - Basic Card Payment - - - - - - -
-

- The Basic Card Payment specification describes the data formats used by the - PaymentRequest API [[!PAYMENT-REQUEST-API]] to support payment by payment cards such as - credit or debit cards. -

-
- -
-

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

-
- -
-

Introduction

-

- This specification is a Payment Transaction Message Specification used by the PaymentRequest API - [[!PAYMENT-REQUEST-API]] to support payment by payment cards such as credit or debit cards. It is intended - to provide compatibility for merchants who currently request card details from customers to ease adoption - of the PaymentRequest API. -

-

- In the future, merchants should favor payment methods that provide a tokenized response rather than - clear text credit card details. -

-
- -
-

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 Request API
-
The term PaymentRequest constructor is defined by the PaymentRequest API - specification [[!PAYMENT-REQUEST-API]].
-
Payment Method Identifiers
-
The term Payment - Method Identifier is defined by the Payment Method Identifiers specification - [[!METHOD-IDENTIFIERS]].
-
Web IDL
-
The IDL in this specification is defined by Web IDL [[!WEBIDL]].
-
-
- -
-

Payment Method Identifier

-

The following payment method identifier strings are supported by the Basic Card Payment data formats.

- - - - - - - - - - - - - - - - - - -
Identifier StringDescription
visaVisa (Credit, Debit and Electron)
visa/creditVisa Credit
visa/debitVisa Debit
visa/electronVisa Electron
mastercardMasterCard (and EuroCard)
mastercard/creditMasterCard Credit
mastercard/debitMasterCard Debit
amexAmerican Express
discoverDiscover
maestroMaestro
dinersDiners Club
jcbJCB
unionpayUnionPay
unionpay/creditUnionPay Credit
unionpay/debitUnionPay Debit
-
- -
-

Payment Method Flow

-

The following represent the flow for all the supported payment method identifier strings as they could be used by a website

-

The blue call-outs show where and how the API is invoked.

- -
- -
- -
-

Payment Method Specific Data for the PaymentRequest constructor

-

This section describes payment method specific data that is supplied as part of the data - argument to the PaymentRequest constructor.

-

There is no payment method specific data used by the PaymentRequest constructor when processing - Basic Card Payment methods.

-
- -
-

Payment Method Response

-

The BasicCardResponse dictionary contains the response from the - PaymentRequest API when a user accepts payment with a Basic Payment Card payment method.

- -
-

BasicCardResponse

- 
-        dictionary BasicCardResponse {
-          DOMString cardholderName;
-          required DOMString cardNumber;
-          DOMString expiryMonth;
-          DOMString expiryYear;
-		  DOMString cardSecurityCode;
-		  
-          BillingAddress? billingAddress;
-        };
-
- -

- The BasicCardResponse dictionary contains the following fields: -

- -
-
cardholderName
-
The cardholderName field contains the cardholder's name as it appears on the card.
-
cardNumber
-
The cardNumber field contains the primary account number (PAN) for the payment card.
-
expiryMonth
-
The expiryMonth field contains a two-digit string for the expiry month - of the card in the range 01 to 12.
-
expiryYear
-
The expiryYear field contains a two-digit string for the expiry year - of the card in the range 00 to 99.
-
cardSecurityCode
-
The cardSecurityCode field contains a three or four digit string for the - security code of the card (sometimes known as the CVV, CVC, CVN, CVE or CID).
- -
- -

-There is a requirement for payment apps to be able to return data that is -hidden from the payee themselves (perhaps for PCI scope reasons) as they will -pass it on to their payment service processor who can then decrypt it and use -it. -

- -
- -
-

BillingAddress

- 
-        dictionary BillingAddress {
-          // [...] fields TBC - most likely the same as shipping address
-        };
-
- -

The BillingAddress dictionary contains the billing address - information associated with the payment card.

- -

- The fields of the BillingAddress will most likely match those in the - shipping address of the PaymentRequest API once those are defined. -

- -
-
- -
- There is an open issue about what values can be supplied to complete. These may depend on the - payment method selected and then Basic Card Payment values would need to be defined in this - document. -
- - - diff --git a/specs/method-identifiers.html b/specs/method-identifiers.html deleted file mode 100644 index 1d9962e9..00000000 --- a/specs/method-identifiers.html +++ /dev/null @@ -1,149 +0,0 @@ - - - - Payment Method Identifiers - - - - - -
-

- The Payment Request API [[!PAYMENT-REQUEST-API]] requires that merchants supply a list - of identifiers for supported payment methods. This document defines those identifier - strings and how they are created. -

-
- -
-

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

-
- -
-

Introduction

-

- One of the principles of the PaymentRequest API is that merchants must know how to accept payments from the payment methods that they claim to support. - This allows the API to abstract away the details of specific payment methods and to add new ones over time without changing the API specification. -

-

- As part of the paymentRequest() call, the web page provides an array of strings that identify the supported payment methods. This document defines those strings. -

-
- -
-

Dependencies

-

This specification relies on several other underlying specifications.

-
-
URL
-
The terms URL, absolute URL, base URL, URL parser, and URL equivalence are defined by [[!url-1-20141209]] (or the editor's draft).
-
-
- -
-

Payment Method Identifier

-

- The Payment Method Identifier is a string that uniquely identifies a payment method that a user can use to complete a transaction. For example, Visa, MasterCard, and American Express are payment methods used in some countries. -

-
-

Identifier format

-

Payment method identifiers are strings containing a URL. The string MUST be an absolute URL.

-
-
-

Identifier equivalence

-

When the PaymentRequest API is invoked, the web page provides a list of identifiers for supported payment methods. - The user agent must compare these identifiers to those available to the user and use this to filter what the user - can select. To determine whether two identifiers match, perform the following test:

-
    -
  • Let A be the first payment method identifier string and let B be the second payment method - identifier string.
    • -
  • Let urlA be the result from the URL parser when parsing A with - no base URL.
    • -
  • Let urlB be the result from the URL parser when parsing B with - no base URL
    • -
  • The identifiers match if urlA equals urlB using the - URL equivalence test (i.e. the test returns true).
    • -
-
-
- -
-

Issues

- -

The following issues are tracking aspects of the payment method identifier specification:

- -
-

Should there be well-known identifiers that are simple strings defined in the spec that don't conform to the distributed extensibility syntax that are used for common payment methods?

-
- -
-

A registration mechanism may exist to install the code for new payment methods into the user agent. This process - would add support for a new payment method to the user agent. This mechanism should be defined in a separate specification.

-

There is an initial outline making a proposal.

-
- -
-

There is an open issue about whether payment method identifiers should resolve to a resource if they are URLs.

-
-
- - - diff --git a/specs/paymentrequest.html b/specs/paymentrequest.html index d0f85ebb..09dd38d9 100644 --- a/specs/paymentrequest.html +++ b/specs/paymentrequest.html @@ -1,1338 +1,19 @@ - - - Payment Request API - - - - - - -
-

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

-
- -
-

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

-
- -
-

Introduction

-

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 [[PAYMENT-ARCH]] document.

- -
-

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
    • -
-
- -
-

Non-goals

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

- 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]] -

- - -
-
-
- -
-

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:

- - - - - - -
TypeMessage (optional)
AbortErrorThe payment request was aborted
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. -

The term extended attribute is defined by [[!WEBIDL]].

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

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

- - 
-        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);
-        });
-
- -
-

PaymentRequest constructor

-

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

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

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.

- 
-            [
-              {
-                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.

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

- - 
-            {
-              requestShipping: true
-            }
-
-
- -
- There is an open issue about whether methodData, details, and data - should be combined into a single object. -
- -
- 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. -
- -
- 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 methodData sequence is zero, then throw - a TypeError. -
    2. -
  2. - For each PaymentMethodData dictionary, if the length of the - supportedMethods sequence is zero, then throw a TypeError. -
    3. -
  3. - If the browsing context of the script calling the constructor is - not a top-level browsing context, then throw a SecurityError. -
    -

    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. -
  4. - If details does not contain a value for total, then throw a - TypeError. -
    5. -
  5. - 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. -
    6. -
  6. - For each PaymentMethodData in methodData, if the data field - is supplied but is not a JSON-serializable object, then throw a TypeError. -
    7. -
  7. Let request be a new PaymentRequest.
    8. -
  8. - 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. -

    -
    9. -
  9. Store details into request@[[\details]].
    10. -
  10. Store options into request@[[\options]].
    11. -
  11. Set the value request@[[\state]] to created.
    12. -
  12. - Set the value of the shippingAddress attribute on request to null. -
    13. -
  13. - Set the value of the shippingOption attribute on request to null. -
    14. -
  14. - If details contains a shippingOptions sequence with a - length of 1, then set shippingOption to the id of - the only ShippingOption in the sequence. -
    15. -
  15. - If details contains a shippingOptions sequence with a - length greater than 1, and if any ShippingOption 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. -
    16. -
  16. Set the value request@[[\updating]] to false.
    17. -
  17. Return request.
    18. -
-
- -
-

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

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

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

- -

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

- -

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

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

State transitions

-

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

- Transition diagram for internal slot state of a PaymentRequest object -
- -
-

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

-
- -
-

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

-
- -
-

Internal Slots

-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - -
Internal SlotDescription (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. -
-
- -
- -
-

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

CurrencyAmount

- 
-dictionary CurrencyAmount {
-  required DOMString currency;
-  required DOMString value;
-};
-
-

- 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). -
- The string should match the regular expression ^-?[0-9]+(\.[0-9]+)?$. -
-
-
- -

The following example shows how to represent US$55.00.

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

PaymentDetails dictionary

- 
-dictionary PaymentDetails {
-  PaymentItem total;
-  sequence<PaymentItem> displayItems;
-  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: -

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

-

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.

-

- If the sequence contains only one item or 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. -

-
-
-
- -
-

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

PaymentItem dictionary

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

-
-
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. -
- There is an open issue about whether it should be possible to provide a PaymentItem - with amounts in more than once currency. -
-
- There is an open issue about whether it should be possible to provide a different amounts depending - upon the payment method. -
-
-
-
- -
-

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

-
- 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? -
-
- -
-

ShippingOption interface

- 
-        dictionary ShippingOption {
-          required string id;
-          required string label;
-          required CurrencyAmount amount;
-          boolean selected = false;
-        };
-
-

- 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. -
-
selected
-
This is set to true to indicate that this is the default selected ShippingOption - in a sequence. User agents SHOULD display this option by default in the user interface.
-
-
- -
-

PaymentResponse interface

- 
-        enum PaymentComplete { "success", "fail", "" };
-
-        interface PaymentResponse {
-          readonly attribute DOMString methodName;
-          readonly attribute object details;
-          readonly attribute PaymentAddress? shippingAddress;
-          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. -
-
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. -
-
- -
-

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:

-
    -
  1. Let promise be a new Promise.
    2. -
  2. - If the value of the internal slot [[\completeCalled]] is true, then throw an InvalidStateError. -
    3. -
  3. Set the value of the internal slot [[\completeCalled]] to true.
    4. -
  4. Return promise and asynchronously perform the remaining steps.
    5. -
  5. 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 "".
    6. -
  6. Resolve promise with undefined.
    7. -
- -
- 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. -
-
- -
-

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

Events

- -
-

Summary

- - - - - - - - - - - - - -
Event nameInterfaceDispatched when...
shippingaddresschangePaymentRequestUpdateEventThe user provides a new shipping address.
shippingoptionchangePaymentRequestUpdateEventThe user chooses a new shipping option.
-
- -
-

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. -
  2. If the dispatch flag is unset, then throw an InvalidStateError.
    3. -
  3. - If [[\waitForUpdate]] is true, then throw an InvalidStateError. -
    4. -
  4. - If target@[[\state]] is not interactive, then throw an - InvalidStateError. -
    5. -
  5. - If target@[[\updating]] is true, then throw - an InvalidStateError. -
    6. -
  6. Set the stop propagation flag and stop immediate propagation flag.
    7. -
  7. Set [[\waitForUpdate]] to true.
    8. -
  8. Set target@[[\updating]] to true.
    9. -
  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.

    -
    - 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. -
  10. Return from the method and asynchronously perform the remaining steps.
    11. -
  11. Wait until d settles.
    12. -
  12. 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. -
    2. - If details contains a displayItems value, then copy - this value to the displayItems field of target@[[\details]]. -
      3. -
    3. - If details contains a shippingOptions sequence, then: -
        -
      1. - Copy the shippingOptions sequence from details to the - shippingOptions field of target@[[\details]]. -
        2. -
      2. Let newOption be null.
        3. -
      3. - If details contains a shippingOptions sequence with a - length of 1, then set newOption to the id of the only - ShippingOption in the sequence. -
        4. -
      4. - If details contains a shippingOptions sequence with a - length greater than 1, 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. -
        5. -
      5. - Set the value of shippingOption on target to - newOption. -
        6. -
      -
      4. -
    -
    13. -
  13. Set [[\waitForUpdate]] to false.
    14. -
  14. Set target@[[\updating]] to false.
    15. -
  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. -
    16. -
- -
-
- -

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

- -
-

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.

- -
-

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. -
  2. Let name be shippingaddresschange.
    3. -
  3. - Set the shippingAddress attribute on request to the - shipping address provided by the user. -
    4. -
  4. - Run the PaymentRequest updated algorithm with request and name. -
    5. -
-
- -
-

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. -
  2. Let name be shippingoptionchange.
    3. -
  3. - Set the shippingOption attribute on request to the - id string of the ShippingOption provided by the user. -
    4. -
  4. - Run the PaymentRequest updated algorithm with request and name. -
    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.

-

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. -
  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. -
  3. Let event be a new PaymentRequestUpdateEvent.
    4. -
  4. - Queue a task to fire an event named name of type event - at request. -
    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. -
  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. -
  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. -
  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. -
  5. - Let response be a new PaymentResponse. -
    6. -
  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. -
  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. -
  8. - If the requestShipping value of request@[[\options]] - is true, then copy the shippingAddress attribute of - request to the shippingAddress attribute of response. -
    9. -
  9. - 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. -
    10. -
  10. - 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. -
    11. -
  11. - Set response@[[\completeCalled]] to false. -
    12. -
  12. - Set request@[[\state]] to closed. -
    13. -
  13. - Resolve the pending promise request@[[\acceptPromise]] with response. -
    14. -
-
-
- -
-

Security Considerations

-

- This section is a placeholder to record security considerations as we gather them through working - group discussion. -

-
-

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

-
-
- -
-

Privacy Considerations

-

- This section is a placeholder to record privacy considerations as we gather them through working - group discussion. -

-
-

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

-
-
- -
-
- The references in the spec need to be up-to-date. -
- - - + + + + + + + + Redirecting to https://w3c.github.io/browser-payment-api/ + + + +

+ This page should redirect you to the new URL of the spec at: https://w3c.github.io/browser-payment-api/
+ If not click here. +

+ + + \ No newline at end of file