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
+ minimal integration. Payment Mediators (e.g. browsers) will facilitate the payment flow between
merchant and user.
@@ -100,11 +100,11 @@
Introduction
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
+
This specification describes an API that allows Payment Mediators (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
+ transaction is passed between the Payment Method and the merchant via the Payment Mediator
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
@@ -118,10 +118,10 @@
Introduction
Goals
-
Allow the user agent to act as intermediary between merchants, users, and payment
+
Allow payment methods to bring more secure payment transactions to the web
@@ -141,29 +141,29 @@
Non-goals
This specification defines one class of products:
-
Conforming user agent
+
Conforming payment mediator
- 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]].
+ A payment mediator MUST behave as described in this specification
+ in order to be considered conformant. In this specification, payment mediator means a Web
+ browser or other cross-platform.
- User agents MAY implement algorithms given in this
+ Payment mediator 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
+ A conforming Payment Request API payment mediator MUST also be a
conforming implementation of the IDL fragments
of this specification, as described in the
“Web IDL” specification. [[!WEBIDL]]
@@ -211,7 +211,7 @@
Dependencies
WebIDL
-
When this specification says to throw an error, the user agent must throw an
+
When this specification says to throw an error, the payment mediator 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.
@@ -242,11 +242,11 @@
PaymentRequest interface
A web page creates a PaymentRequest to make a payment request. This is
- typically associated with the user initiating a payment process
+ 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.
+ payment mediator while the user is providing input before approving or denying a payment request.
The following example shows how to construct a PaymentRequest and begin the
@@ -276,11 +276,11 @@
PaymentRequest constructor
method specific data.
- 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
+ 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.
@@ -369,13 +369,13 @@
PaymentRequest constructor
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
+ methods should be passed to the payment mediator 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
+ events for exchange of data between the payment mediator and the website is
the best design for this API. An alternative pattern has been
proposed in the issue thread.
@@ -485,7 +485,7 @@
show()
Let acceptedMethods be the sequence of payment method identifiers request@[[\supportedMethods]]
- with all identifiers removed that the user agent does not accept.
+ with all identifiers removed that the payment mediator does not accept.
If the length of acceptedMethods is zero, then reject acceptPromise with a NotSupportedError.
@@ -516,7 +516,7 @@
abort()
State transitions
The internal slot [[\state]] follows the following state transitions:
-
@@ -605,13 +605,13 @@
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
+
+ The resolution of the WG per Issue #57 defined
+ a format for currencies and amounts that lacked support for negative values. The format below adds this
capability in a way that is not common for financial messaging standards (using signed numbers). The
rationale for negative numbers is to support discounts. The group is still discussing whether functionality
to support discounts might be implemented in a different manner (e.g., via a transaction type).
-
+
A CurrencyAmount dictionary is used to supply monetary amounts.
The following fields MUST be supplied for a CurrencyAmount to be valid:
@@ -622,13 +622,13 @@
CurrencyAmount
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.
+ payment mediators 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
+ 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]+)?$.
@@ -668,7 +668,7 @@
PaymentDetails dictionary
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
+ request. The payment mediator 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.
shippingOptions
@@ -706,7 +706,7 @@
PaymentOptions dictionary
requestShipping
- This boolean value indicates whether the user agent should collect and return
+ This boolean value indicates whether the payment mediator 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.
@@ -737,7 +737,7 @@
PaymentItem dictionary
This is a string identifier used to reference this PaymentItem. It MUST be
unique for a given PaymentRequest.
label
-
This is a human-readable description of the item. The user agent may display
+
This is a human-readable description of the item. The payment mediator may display
this to the user.
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?
+ to request from the payment mediator. Is capturing email and recipient phone important to you?
@@ -803,7 +803,7 @@
ShippingOption interface
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
+
This is a human-readable description of the item. The payment mediator SHOULD use this
string to display the shipping option to the user.
amount
@@ -930,7 +930,7 @@
PaymentRequestUpdateEvent
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.
+ dictionary containing changed values that the payment mediator SHOULD present to the user.
The PaymentRequestUpdateEvent constructor MUST set the internal slot [[\waitForUpdate]]
to false.
The updateWith method MUST act as follows:
@@ -955,15 +955,15 @@
PaymentRequestUpdateEvent
Set [[\waitForUpdate]] to true.
Set target@[[\updating]] to true.
- The user agent SHOULD disable the user interface that allows the user to accept
+ The payment mediator 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
+
The payment mediator 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 within a reasonable amount of time then the payment mediator behaves as if
the promise was rejected.
@@ -995,8 +995,8 @@
PaymentRequestUpdateEvent
Set [[\waitForUpdate]] to false.
Set target@[[\updating]] to false.
- The user agent should update the user interface based on any changed values
- in target. The user agent SHOULD re-enable user interface elements that might
+ The payment mediator should update the user interface based on any changed values
+ in target. The payment mediator SHOULD re-enable user interface elements that might
have been disabled in the steps above if appropriate.
@@ -1022,7 +1022,7 @@
PaymentRequestUpdateEvent
Algorithms
When the internal slot [[\state]] of a PaymentRequest object is set to
- interactive, the user agent will trigger the following algorithms based
+ interactive, the payment mediator will trigger the following algorithms based
on user interaction.
@@ -1080,7 +1080,7 @@
PaymentRequest updated algorithm
If the request@[[\state]] is not set to interactive,
- then terminate this algorithm and take no further action. The user agent user interface
+ then terminate this algorithm and take no further action. The payment mediator user interface
should ensure that this never occurs.
The PaymentRequest interface allows a web page to call abort
- to tell the user agent to abort the payment request and to tear down any user interface that
+ to tell the payment mediator to abort the payment request and to tear down any user interface that
might be shown. 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
+ A payment mediator might not always be able to abort a request. For example, if the payment mediator
has delegated responsibility for the request to another app. To support this situation,
- the user agent must run the User agent delegates payment request algorithm.
+ the payment mediator must run the Payment mediator delegates payment request algorithm.
The algorithm MUST run the following steps:
@@ -1116,12 +1116,12 @@
User agent delegates payment request algorithm
If the request@[[\updating]] is true, then terminate this
- algorithm and take no further action. The user agent user interface should ensure
+ algorithm and take no further action. The payment mediator user interface should ensure
that this never occurs.
If the request@[[\state]] is not interactive, then terminate this
- algorithm and take no further action. The user agent user interface should ensure
+ algorithm and take no further action. The payment mediator user interface should ensure
that this never occurs.
@@ -1138,19 +1138,19 @@
User agent delegates payment request algorithm
-
We believe there are user agent configurations that can cause the UI to get into a state
+
We believe there are payment mediator configurations that can cause the UI to get into a state
where cancellation by the web page during user interaction is difficult. Users should still
be able to cancel the payment but script will not be able to. We need to investigate in more
detail the consequences of this and whether it is really needed.
-
If we specify delegated then it isn't necessary for all user agents to be
+
If we specify delegated then it isn't necessary for all payment mediators to be
able to move to this state but it would be necessary for all payment flows that wish to call
abort to account for the situation where this may fail in the delegated
state.
- This specification should describe how the user agent will pass the
- payment request data and the complete signal to a native payment app
+ This specification should describe how the payment mediator 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.
@@ -1170,13 +1170,13 @@
User accepts the payment request algorithm
If the request@[[\updating]] is true, then terminate this
- algorithm and take no further action. The user agent user interface should ensure
+ algorithm and take no further action. The payment mediator user interface should ensure
that this never occurs.
If request@[[\state]] is not interactive and
the not delegated, then terminate this algorithm and take no further action.
- The user agent user interface should ensure that this never occurs.
+ The payment mediator user interface should ensure that this never occurs.
If the requestShipping value of request@[[\options]]
