Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
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.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
The working group maintains a list of all bug reports that the group has not yet addressed. This draft highlights some of the pending issues that are still to be discussed in the working group. No decision has been taken on the outcome of these issues including whether they are valid. Pull requests with proposed specification text for outstanding issues are strongly encouraged.
This specification was derived from a report published previously by the Web Platform Incubator Community Group.
This document was published by the Web Payments Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-payments-wg@w3.org (subscribe, archives). All comments are welcome.
Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 September 2015 W3C Process Document.
This section is non-normative.
Buying things on the web, particularly on mobile, can be a frustrating experience for users. Every web site has its own flow and its own validation rules, and most require users to manually type in the same set of information over and over again. Likewise, it is difficult and time consuming for developers to create good checkout flows that support various payment schemes.
This specification describes an API that allows user agents (e.g. browsers) to act as an intermediary between the three key parties in every transaction: the merchant (e.g. an online web store), the buyer (e.g. the user buying from the online web store), and the Payment Method (e.g. credit card). Information necessary to process and confirm a transaction is passed between the Payment Method and the merchant via the user agent with the buyer confirming and authorizing as necessary across the flow.
In addition to better, more consistent user experiences, this also enables web sites to take advantage of more secure payment schemes (e.g. tokenization and system-level authentication) that are not possible with standard JavaScript libraries. This has the potential to reduce liability for the merchant and helps protect sensitive user information.
The API described in this document forms part of the Payment Request system described in the Payment Request Architecture [PAYMENTARCH] document.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, and SHOULD are to be interpreted as described in [RFC2119].
This specification defines one class of products:
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]
This specification relies on several other underlying specifications.
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.
Event
type and the terms fire an event, dispatch flag,
stop propagation flag, and stop immediate propagation flag are defined by [DOM4].
DOMException and the following DOMException types from [DOM4] are used:
Type | Message (optional) |
---|---|
InvalidStateError | The object is in an invalid state |
NotSupportedError | The payment method was not supported |
SecurityError | The operation is only supported in a secure context |
[Constructor(sequence<DOMString> supportedMethods, PaymentDetails
details, optional PaymentOptions
options, optional object data)]
interface PaymentRequest : EventTarget {
Promise<PaymentResponse
> show();
void abort();
readonly attribute ShippingAddress
? shippingAddress;
readonly attribute DOMString? shippingOption;
// Supports "shippingaddresschange" event
attribute EventHandler onshippingaddresschange;
// Supports "shippingoptionchange" event
attribute EventHandler onshippingoptionchange;
};
A web page creates a
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.
PaymentRequest
The following example shows how to construct a
and begin the
user interaction:PaymentRequest
var payment = new PaymentRequest(supportedMethods, details, options, data); payment.addEventListener("shippingaddresschange", function (changeEvent) { // Process shipping address change }); payment.show().then(function(paymentResponse) { // Process paymentResponse // paymentResponse.methodName contains the selected payment method // paymentResponse.details contains a payment method specific response paymentResponse.complete(true); }).catch(function(err) { console.error("Uh oh, something bad happened", err.message); });
The
is constructed using the supplied PaymentRequest
supportedMethods
list, the payment details
, the payment options
, and any payment
method specific data
.
The supportedMethods
sequence contains the payment method identifiers
for the payment methods that the merchant web site accepts.
["visa", "bitcoin", "bobpay.com"]
The details
object contains information about the transaction that the
user is being asked to complete such as the line items in an order.
{ "items": [ { "id": "basket", "label": "Sub-total", "amount": { "currency": "USD", "value" : "55.00" }, // US$55.00 }, { "id": "tax", "label": "Sales Tax", "amount": { "currency": "USD", "value" : "5.00" }, // US$5.00 }, { "id": "total", "label": "Total due", "amount": { "currency": "USD", "value" : "60.00" }, // US$60.00 } ] }
The options
object contains information about what options the web page
wishes to use from the payment request system.
{ "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" } }
supportedMethods
, details
, and data
should be combined into a single object.
navigator.payments
, using a factory method to create an instance, or using a constructor as
currently described in the specification.
The
constructor MUST act as follows:
PaymentRequest
supportedMethods
sequence is zero, then throw
a TypeError
.
SecurityError
.
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.
details
does not contain a sequence of items
with length greater
than zero, then throw a TypeError
.
data
is not a JSON-serializable object, then throw a TypeError
.
data
does not match one of the payment method identifiers
in supportedMethods
, then throw a TypeError
.
TypeError
.
PaymentRequest
.supportedMethods
into request@[[supportedMethods]].details
into request@[[details]].options
into request@[[options]].data
into request@[[data]].shippingAddress
attribute on request to null.
shippingOption
attribute on request to null.
details
contains a shippingOptions
sequence with a
length of 1, then set shippingOption
to the id
of
the only ShippingOption
in the sequence.
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.
It may help users understand what they are accepting if the web site is able to label the "accept" button. For example, if a user is about to "Buy" something, "Reserve" something, "Subscribe" to something, etc. That said, this may create payment interface/experience issues and accidentally lead to customers thinking they're performing actions like a one-time purchase, when they are in fact signing up for a subscription.
The
method MUST act as follows:
show
PaymentRequest
object on which the method is called..
InvalidStateError
.NotSupportedError
.
The abort
method may be called if the web page wishes to abort the payment
request after the
method has been called and before the [[acceptPromise]]
has been resolved.show
The
method MUST act as follows:abort
InvalidStateError
.The internal slot [[state]] follows the following state transitions:
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
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
.
Instances of
are created with the internal slots in
the following table:PaymentRequest
Internal Slot | Description (non-normative) |
---|---|
[[supportedMethods]] | The supportMethods supplied to the constructor. |
[[details]] |
The current for the payment request initially
supplied to the constructor and then updated with calls to .
|
[[options]] | The supplied to the constructor. |
[[data]] |
The payment method specific data supplied to the constructor used
by a Payment App to influence the app's behavior.
|
[[state]] | The current state of the payment request. |
[[updating]] |
true is there is a pending call to update
the payment request and false otherwise.
|
[[acceptPromise]] |
The pending Promise created during that will be
resolved if the user accepts the payment request.
|
dictionary CurrencyAmount {
required DOMString currency;
required DOMString value;
};
A
dictionary is used to supply monetary amounts.
The following fields MUST be supplied for a CurrencyAmount
to be valid:
CurrencyAmount
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
^-?[0-9]+(\.[0-9]+)?$
.
The following example shows how to represent US$55.00.
{ "currency": "USD", "value" : "55.00" }
dictionary PaymentDetails
{
sequence<PaymentItem
> items;
sequence<ShippingOption
> shippingOptions;
};
The PaymentDetails
dictionary is passed to the
constructor and provides information about the requested transaction. The PaymentRequest
PaymentDetails
dictionary is also used to update the payment request using
.
updateWith
The following fields are part of the PaymentDetails
dictionary:
items
PaymentItem
dictionaries indicates what the payment
request is for. The sequence must contain at least one PaymentItem
. The last
PaymentItem
in the sequence represents the total amount of the payment
request. It is the responsibility of the calling code to ensure that the total amount is
the sum of the preceding items. The user agent MAY not validate that this is true.
shippingOptions
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
will be set to the shippingOption
id
of this option without running the shipping option changed algorithm.
items
sequence should special-case the last
item in the sequence to represent the total.
dictionary PaymentOptions
{
boolean requestShipping = false;
};
The PaymentOptions
dictionary is passed to the
constructor and provides information about the options desired for the payment request.
PaymentRequest
The following fields MAY be passed to the
constructor:
PaymentRequest
requestShipping
true
when physical goods need to be shipped by the merchant to the user.
This would be set to false
for an online-only electronic purchase transaction.
If this value is not supplied then the the PaymentRequest
behaves as
if a value of false
had been supplied.
dictionary PaymentItem {
required DOMString id;
required DOMString label;
required CurrencyAmount
amount;
};
A sequence of one or more PaymentItem
dictionaries is included in the
dictionary to indicate the what the payment request is for and the value asked for.
PaymentDetails
The following fields MUST be included in a PaymentItem
for it to be valid:
id
PaymentItem
. It MUST be
unique for a given PaymentRequest
.label
amount
CurrencyAmount
containing the monetary amount for the item.
PaymentItem
with amounts in more than once currency.
interface ShippingAddress
{
// [...] fields TBC
};
If the requestShipping
flag was set to true
in the PaymentOptions
passed to the PaymentRequest
constructor, then the user agent will populate the
shippingAddress
field of the
object with
the user's selected shipping address.
PaymentRequest
ShippingAddress
interface are
yet to be defined.
dictionary ShippingOption
{
required string id;
required string label;
required CurrencyAmount
amount;
};
The ShippingOption
dictionary has fields describing a shipping option. A web page can
provide the user with one or more shipping options by calling the updateWith
method in response to a change event.
The following fields MUST be included in a PaymentItem
for it to be valid:
id
ShippingOption
. It MUST be
unique for a given PaymentRequest
.label
amount
CurrencyAmount
containing the monetary amount for the item.
interface PaymentResponse
{
readonly attribute DOMString methodName;
readonly attribute object details;
Promise<void> complete(boolean success);
};
A PaymentResponse
is returned when a user has selected a payment method and
approved a payment request. It contains the following fields:
methodName
details
The complete
method must be called after the user has accepted the payment
request and the [[acceptPromise]] has been resolved. The complete
method
takes a boolean argument that indicates the payment was successfully processed if true
and
that processing failed if false
. Calling the complete
method tells the user
agent that the user interaction is over (and should cause any remaining user interface to be closed).
The
method MUST act as follows:complete
InvalidStateError
.
success
to the Payment App that accepted the
payment request.
undefined
.Instances of
are created with the internal slots in
the following table:PaymentResponse
Internal Slot | Description (non-normative) |
---|---|
[[completeCalled]] |
true if the method has been called and false
otherwise.
|
This section is non-normative.
Event name | Interface | Dispatched when... |
---|---|---|
shippingaddresschange |
PaymentRequestUpdateEvent |
The user provides a new shipping address. |
shippingoptionchange |
PaymentRequestUpdateEvent |
The user chooses a new shipping option. |
[Constructor(DOMString type, optionalPaymentRequestUpdateEventInit
eventInitDict)] interface PaymentRequestUpdateEvent :Event
{ void updateWith(Promise<PaymentDetails
> d); }; dictionary PaymentRequestUpdateEventInit : EventInit { };
The
enables the web page to update
the details of the payment request in response to a user interaction.PaymentRequestUpdateEvent
If the web page wishes to update the payment request then it should call
and provide a promise that will resolve with a updateWith
dictionary containing changed values that the user agent SHOULD present to the user.PaymentDetails
The PaymentRequestUpdateEvent constructor MUST set the internal slot [[waitForUpdate]] to false.
The updateWith
method MUST act as follows:
PaymentRequest
object that is the target of
the event.
InvalidStateError
.InvalidStateError
.
InvalidStateError
.
InvalidStateError
.
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.
d
settles.d
is resolved with details
and details
is a
PaymentDetails
dictionary, then:
details
contains an items
value, then copy
this value to the items
field of target@[[details]].
details
contains a shippingOptions
sequence, then
copy this value to the shippingOptions
field of target@[[details]].
details
contains a shippingOptions
sequence with a
length of 1, then set newOption to the id
of the only
ShippingOption
in the sequence.
shippingOption
on target to
newOption.
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.)
The spec should indicate how data might be passed securely through the API using mechanisms such as field level encryption and message signing. While these may not be standardised a reference to the payment method specifications would be appropriate as well as some examples of how those specifcations might implement secure messaging.
When the internal slot [[state]] of a
object is set to
interactive, the user agent will trigger the following algorithms based
on user interaction.PaymentRequest
The shipping address changed algorithm runs when the user provides a new shipping address. It MUST run the following steps:
PaymentRequest
object that the user is
interacting with.shippingaddresschange
.shippingAddress
attribute on request to the
shipping address provided by the user.
The shipping option changed algorithm runs when the user chooses a new shipping option. It MUST run the following steps:
PaymentRequest
object that the user is
interacting with.shippingoptionchange
.shippingOption
attribute on request to the
id
string of the ShippingOption
provided by the user.
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
called request with an event name of name.PaymentRequest
It MUST run the following steps:
PaymentRequestUpdateEvent
.
The
interface allows a web page to call PaymentRequest
abort
to tell the user agent to abort the payment request and to tear down any user interface that
might be shown. For example, a web page may choose to do this the goods they are selling are
only available for a limited amount of time. If the user does not accept the payment request
within the allowed time period, then the request will be aborted.
A user agent may not always be able to abort a request. For example, if the user agent has delegated responsibility for the request to another app. To support this situation, the user agent must run the User agent delegates payment request algorithm. The algorithm MUST run the following steps:
PaymentRequest
object that the user is
interacting with.
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.
We believe there are user agent configurations that can cause the UI to get into a state where cancellation by the web page during user interaction is difficult. Users should still be able to cancel the payment but script will not be able to. We need to investigate in more detail the consequences of this and whether it is really needed.
If we specify delegated
then it isn't necessary for all user agents to be
able to move to this state but it would be necessary for all payment flows that wish to call
to account for the situation where this may fail in the abort
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 and also how it will receive the payment response from the payment app.
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:
PaymentRequest
object that the user is
interacting with.
delegated
, then terminate this algorithm and take no further action.
The user agent user interface should ensure that this never occurs.
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.
PaymentResponse
.
methodName
attribute value of response to the payment method identifier
for the payment method that the user selected to accept the payment.
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.