- [Constructor(sequence<DOMString> supportedMethods, PaymentDetails details, optional PaymentOptions options, optional object data)]
+ [Constructor(PaymentDetails details, optional PaymentOptions options)]
interface PaymentRequest : EventTarget {
Promise<PaymentResponse> show();
void abort();
@@ -253,7 +254,7 @@ PaymentRequest interface
user interaction:
- var payment = new PaymentRequest(supportedMethods, details, options, data);
+ var payment = new PaymentRequest(details, options);
payment.addEventListener("shippingaddresschange", function (changeEvent) {
// Process shipping address change
});
@@ -271,9 +272,8 @@ PaymentRequest interface
PaymentRequest constructor
- The PaymentRequest is constructed using the supplied supportedMethods
- list, the payment details, the payment options, and any payment
- method specific data.
+ The PaymentRequest is constructed using the payment details (which are passed
+ to the selected payment app) and the payment options which are processed by the user agent.
It is proposed that a conformance criteria for implementations of this API be
@@ -284,16 +284,78 @@ PaymentRequest constructor
payment app.
- The supportedMethods sequence contains the payment method identifiers
- for the payment methods that the merchant web site accepts.
+
+ The details contains the core payment request data that will be passed on to the user selected
+ payment app.
+
+ The amount sequence contains the amount (possibly in different currencies) that the website
+ is requesting to be paid.
+
+ The supportedMethods sequence contains the payment methods that the merchant web
+ site accepts. Each payment method is linked to one or more payment method identifiers.
+
+ The identifers sequence contains the payment method identifiers that identify the
+ payment methods the web site supports and for which the associated data is part of the
+ request.
+
+ data is a JSON-serializable object that provides optional information that might
+ be needed by the supported payment methods.
+
- ["visa", "bitcoin", "bobpay.com"]
+ {
+ "amount" : [{
+ "currency" : "USD",
+ "value" : "55.00"
+ }],
+ "supportedMethods" : [
+ {
+ "identifers" : ["visa", "mastercard"],
+ "data" : {}
+ },
+ {
+ "identifers" : ["bobpay.com"],
+ "data" : {
+ "merchantIdentifier" : "XXXX",
+ "bobPaySpecificField" : true
+ }
+ },
+ {
+ "identifiers" : ["bitcoin"],
+ "data" : {
+ "address" : "XXXX"
+ }
+ }
+ ]
+ }
- The details object contains information about the transaction that the
- user is being asked to complete such as the line items in an order.
+ The options object contains information that is processed by the user agent. This MAY
+ include processing instructions such as a request to capture a user's shipping details or provide
+ supplimentary information to the payment details that the user agent can use to deliver a rich
+ user experience.
+
+ The shippingOptions object contains the various shipping options which the user agent
+ SHOULD present to the user if the web site has requested that it gather shipping data.
+
+ The items object contains information about the transaction that the
+ user is being asked to complete which the user agent MAY use to supplement the interface presented
+ to the user.
+
{
+ "requestShipping": true,
+ "shippingOptions" : [
+ {
+ "id" : "free",
+ "label" : "5 day Free Shipping",
+ "amount" : { "currency": "USD", "value" : "0" },
+ },
+ {
+ "id" : "express",
+ "label" : "Express Overnight Shipping",
+ "amount" : { "currency": "USD", "value" : "5.00" },
+ },
+ ],
"items": [
{
"id": "basket",
@@ -313,35 +375,8 @@ PaymentRequest constructor
]
}
-
- The options object contains information about what options the web page
- wishes to use from the payment request system.
-
-
- {
- "requestShipping": true
- }
-
-
- data is a JSON-serializable object that provides optional information that might
- be needed by the supported payment methods.
-
- {
- "bobpay.com": {
- "merchantIdentifier": "XXXX",
- "bobPaySpecificField": true
- },
- "bitcoin": {
- "address": "XXXX"
- }
- }
-
-
- There is an open issue about whether supportedMethods, details, and data
- should be combined into a single object.
-
There is an open issue about how a payment request is initiated. The options proposed include using a singleton
@@ -367,12 +402,6 @@ PaymentRequest constructor
a preference and allow users to express a preference that overrides merchant preferences.
-
- There is an open issue about whether the list of supported payment
- methods should be passed to the user agent as a simple sequence of
- strings or as a more complex and flexible object structure.
-
-
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
@@ -385,7 +414,7 @@ PaymentRequest constructor
+ - If the length of the
amount sequence is zero, then throw
+ a TypeError.
-
- If
details does not contain a sequence of items with length greater
- than zero, then throw a TypeError.
-
- -
- If
data is not a JSON-serializable object, then throw a TypeError.
-
- -
- If the name of any top level field of
data does not match one of the payment method identifiers
- in supportedMethods, then throw a TypeError.
-
- -
- If the value of any top level field is not a JSON-serializable object, then
- throw a
TypeError.
+ For each method in supportedMethods:
+
+ - If the length of the
method.identifiers sequence is zero, then throw
+ a TypeError.
+ - If
method.data is not a JSON-serializable object, then throw a
+ TypeError.
+
- Let request be a new
PaymentRequest.
- - Store
supportedMethods into request@[[\supportedMethods]].
- Store
details into request@[[\details]].
- Store
options into request@[[\options]].
- - Store
data into request@[[\data]].
- Set the value request@[[\state]] to created.
-
Set the value of the
shippingAddress attribute on request to null.
@@ -435,7 +458,7 @@ PaymentRequest constructor
Set the value of the shippingOption attribute on request to null.
-
- If
details contains a shippingOptions sequence with a
+ If options contains a shippingOptions sequence with a
length of 1, then set shippingOption to the id of
the only ShippingOption in the sequence.
@@ -467,7 +490,7 @@ show()
-
- Let request be the
PaymentRequest object on which the method is called..
+ Let request be the PaymentRequest object on which the method is called.
- If the value of request@[[\state]] is not created then
throw an
InvalidStateError.
@@ -484,8 +507,20 @@ show()
Return acceptPromise and asynchronously perform the remaining steps.
-
- Let acceptedMethods be the sequence of payment method identifiers request@[[\supportedMethods]]
- with all identifiers removed that the user agent does not accept.
+ Let acceptedMethods be an empty sequence.
+
+ - For each
PaymentMethod in method in sequence request@[[\details]].supportedMethods.
+
+ - For each identifier in method.
identifiers:
+
+ - If acceptedMethods already contains this identifier move onto the next identifier, if
+ there is one.
+ - If the user agent does not have a registered payment app that supports the payment
+ method identified by this identifier move onto the next identifier, if there is one.
+ - Append identifer to the sequence acceptedMethods.
+
+
+
-
If the length of acceptedMethods is zero, then reject acceptPromise with a
NotSupportedError.
@@ -552,10 +587,6 @@ Internal Slots
the following table:
Internal Slot Description (non-normative)
- [[\supportedMethods]]
- The supportMethods supplied to the constructor.
-
[[\details]]
@@ -565,13 +596,9 @@ Internal Slots
[[\options]]
- The PaymentOptions supplied to the constructor.
-
-
- [[\data]]
- The payment method specific data supplied to the constructor used
- by a Payment App to influence the app's behavior.
+ The current PaymentOptions for the payment request initially
+ supplied to the constructor and then updated with calls to updateWith.
@@ -597,6 +624,39 @@ Internal Slots
+
+ PaymentDetails dictionary
+
+dictionary PaymentDetails {
+ sequence<CurrencyAmount> amount;
+ sequence<PaymentMethod> supportedMethods;
+};
+
+
+
+ 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:
+
+
+ amount-
+ This sequence of
CurrencyAmount dictionaries indicates the amount that is being
+ requested. The sequence must contain at least one CurrencyAmount. If the seqeunce contains
+ multiple CurrencyAmount dictionaries it should not contain more than one with the same
+ currency value.
+
+ supportedMethods-
+ This sequence of
PaymentMethod dictionaries indicates which payment methods
+ can be used to process this payment request.
+
+
+
+
CurrencyAmount
@@ -605,13 +665,17 @@ CurrencyAmount
required DOMString value;
};
-
- The resolution of the WG per Issue #57 defined
- a format for currencies and amounts that lacked support for negative values. The format below adds this
- capability in a way that is not common for financial messaging standards (using signed numbers). The
- rationale for negative numbers is to support discounts. The group is still discussing whether functionality
- to support discounts might be implemented in a different manner (e.g., via a transaction type).
-
+
+ The resolution of the WG per Issue #57 defined
+ a format for currencies and amounts that lacked support for negative values. The format below adds this
+ capability in a way that is not common for financial messaging standards (using signed numbers). The
+ rationale for negative numbers is to support discounts. The group is still discussing whether functionality
+ to support discounts might be implemented in a different manner (e.g., via a transaction type).
+
+
+ There is an open issue about whether and how to handle
+ non-decimal currencies.
+
A CurrencyAmount dictionary is used to supply monetary amounts.
The following fields MUST be supplied for a CurrencyAmount to be valid:
@@ -627,8 +691,8 @@
CurrencyAmount
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
+ 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]+)?$.
@@ -646,64 +710,64 @@ CurrencyAmount
- PaymentDetails dictionary
+ PaymentMethod
-dictionary PaymentDetails {
- sequence<PaymentItem> items;
- sequence<ShippingOption> shippingOptions;
+dictionary PaymentMethod {
+ required sequence<DOMString> identifiers;
+ object data;
};
-
-
- 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.
-
+
+ There is an open issue about whether it should be possible to provide a different amounts depending
+ upon the payment method. This could be achevied by having an amount member on the
+ PaymentMethod dictionary.
+
- The following fields are part of the PaymentDetails dictionary:
+ A PaymentMethod dictionary is used to provide the payment method data for the
+ request. Only the identifers field MUST be supplied for a PaymentMethod
+ to be valid.
- itemsidentifiers-
- This sequence of
PaymentItem dictionaries indicates what the payment
- request is for. The sequence must contain at least one PaymentItem. The last
- PaymentItem in the sequence represents the total amount of the payment
- request. The user agent MAY validate that the total amount is the sum of the
- preceding items, but it is the responsibility of the calling code to ensure that.
+ identifers is a sequence of payment method identifiers.
- shippingOptionsdata-
- 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.
+ data is a JSON-serializable object containing any payment method data that must be passed
+ to the payment app.
-
-
- There is an open issue about whether the items sequence should special-case the last
- item in the sequence to represent the total.
-
PaymentOptions dictionary
dictionary PaymentOptions {
+ sequence<PaymentItem> items;
boolean requestShipping = false;
+ sequence<ShippingOption> shippingOptions;
};
-
The PaymentOptions dictionary is passed to the PaymentRequest
- constructor and provides information about the options desired for the payment request.
+ constructor and provides supplimentary data to the user agent for processing the payment request. The
+ PaymentOptions dictionary is also used to update the payment request using
+ updateWith
+
+
+ The PaymentOptions dictionary MUST not be passed on to the payment app.
- The following fields MAY be passed to the PaymentRequest constructor:
+ The following fields MAY be set on the PaymentOptions dictionary:
+ items-
+ This sequence of
PaymentItem dictionaries indicates what the payment request is for.
+ The user agent MAY render this information to the user to provide them with additional details
+ about the payment request.
+
requestShipping-
This boolean value indicates whether the user agent should collect and return
@@ -713,6 +777,15 @@
PaymentOptions dictionary
If this value is not supplied then the the PaymentRequest behaves as
if a value of false had been supplied.
+ shippingOptions-
+ A sequence containing the different shipping options that the user may choose from.
+
If the sequence is empty, then this indicates that the merchant
+ cannot ship to the current shippingAddress.
+ If the sequence only contains one item, then this is the shipping option that
+ will be used and shippingOption will be set to the id
+ of this option without running the shipping option changed algorithm.
+
@@ -726,8 +799,8 @@ PaymentItem dictionary
};
- 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.
+ A sequence of one or more PaymentItem dictionaries is included in the PaymentOptions
+ dictionary to indicate 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:
@@ -742,18 +815,6 @@
PaymentItem dictionary
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.
-
-
- There is an open issue about whether and how to handle
- non-decimal currencies.
-
@@ -796,7 +857,7 @@ ShippingOption interface
method in response to a change event.
- The following fields MUST be included in a PaymentItem for it to be valid:
+ The following fields MUST be included in a ShippingOption for it to be valid:
idPaymentResponse interface
interface PaymentResponse {
readonly attribute DOMString methodName;
+ readonly attribute CurrencyAmount amount;
readonly attribute object details;
Promise<void> complete(boolean success);
@@ -828,11 +890,15 @@ PaymentResponse interface
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.
-
+ methodName-
+ The payment method identifier for the payment method that the user selected
+ to fulfil the transaction.
+
+ amount-
+ The amount that the user has agreed to pay.
+
details-
A JSON-serializable object that provides a payment method specific message used by the merchant to
@@ -920,7 +986,7 @@
PaymentRequestUpdateEvent
[Constructor(DOMString type, optional PaymentRequestUpdateEventInit eventInitDict)]
interface PaymentRequestUpdateEvent : Event {
- void updateWith(Promise<PaymentDetails> d);
+ void updateWith(Promise<PaymentOptions> o, Promise<PaymentDetails> d);
};
dictionary PaymentRequestUpdateEventInit : EventInit {
@@ -929,8 +995,9 @@ PaymentRequestUpdateEvent
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.
+ and provide a promise that will resolve with a PaymentOptions and a promise that will
+ resolve with a PaymentDetails dictionary containing changed values that the
+ user agent SHOULD present to the user and pass to the payment app.
The PaymentRequestUpdateEvent constructor MUST set the internal slot [[\waitForUpdate]]
to false.
The updateWith method MUST act as follows:
@@ -957,32 +1024,32 @@ PaymentRequestUpdateEvent
-
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.
+ has made changes required by the change. The web page MUST settle the promises o and
+ 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.
+ the promises within a reasonable amount of time then the user agent behaves as if
+ one of the promises was rejected.
- Return from the method and asynchronously perform the remaining steps.
- - Wait until
d settles.
- - If
d is resolved with details and details is a
- PaymentDetails dictionary, then:
+ - Wait until
o settles.
+ - If
o is resolved with options and options is a
+ PaymentOptions dictionary, then:
-
- If
details contains an items value, then copy
- this value to the items field of target@[[\details]].
+ If options contains an items value, then copy
+ this value to the items field of target@[[\option]].
-
- If
details contains a shippingOptions sequence, then
- copy this value to the shippingOptions field of target@[[\details]].
+ If options contains a shippingOptions sequence, then
+ copy this value to the shippingOptions field of target@[[\options]].
- Let newOption be null.
-
- If
details contains a shippingOptions sequence with a
+ If options contains a shippingOptions sequence with a
length of 1, then set newOption to the id of the only
ShippingOption in the sequence.
@@ -992,6 +1059,20 @@ PaymentRequestUpdateEvent
+ - Wait until
d settles.
+ - If
d is resolved with details and details is a
+ PaymentDetails dictionary, then:
+
+ -
+ If
details contains an amount sequence, then copy
+ this value to the amount field of target@[[\details]].
+
+ -
+ If
details contains a supportedMethods sequence, then
+ copy this value to the supportedMethods field of target@[[\details]].
+
+
+
- Set [[\waitForUpdate]] to false.
- Set target@[[\updating]] to false.
-