W3C Candidate Recommendation Draft
Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
This specification standardizes an API to allow merchants (i.e. web sites selling physical or digital goods) to utilize one or more payment methods with minimal integration. User agents (e.g., browsers) facilitate the payment flow between merchant and user.
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
In September 2022 the Web Payments Working Group published a Payment Request Recommendation. Following privacy and internationalization reviews, the Recommendation excluded capabilities related to billing and shipping addresses. However, implementations have continued to support those features interoperably, and so the Working Group has decided to try to re-align the specification with implementations, and re-engage the community on associated issues.
This document is a Candidate Recommendation Snapshot based on the text of the original Recommendation. A subsequent Candidate Recommendation Draft will add back address capabilities and a small number of other changes made since publication of the Recommendation.
As part of adding back support for addresses, this specification now refers to the address components defined in the Contact Picker API rather than define those components itself. Indeed, the Contact Picker API is derived from the original definitions found in Payment Request API, and pulled out of the specification because addresses are useful on the Web beyond payments.
The Working Group plans to engage in discussion and follow the usual review process before advancing the specification to Proposed Recommendation status.
The working group will demonstrate implementation experience by producing an implementation report. The report will show two or more independent implementations passing each mandatory test in the test suite (i.e., each test corresponds to a MUST requirement of the specification).
This document was published by the Web Payments Working Group as a Candidate Recommendation Draft using the Recommendation track.
Publication as a Candidate Recommendation does not imply endorsement by W3C and its Members. A Candidate Recommendation Draft integrates changes from the previous Candidate Recommendation that the Working Group intends to include in a subsequent Candidate Recommendation Snapshot.
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. Future updates to this specification may incorporate new features.
This document was produced by a group operating under the 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 03 November 2023 W3C Process Document.
This section is non-normative.
This specification describes an API that allows user agents (e.g., browsers) to act as an intermediary between three parties in a transaction:
A payment method defines:
PaymentMethodData
's data
member. If not specified for a given payment method, no conversion to
IDL is done and the payment method will receive
data
as JSON.
data
member of the PaymentMethodData
,
after it is converted to the payment method's additional data type. If not specified for a given payment
method, no validation is done.
The details of how to fulfill a payment request for a given payment method is an implementation detail of a payment handler, which is an application or service that handles requests for payment. Concretely, a payment handler defines:
Steps that describe how to handle the user changing payment method
or monetary instrument (e.g., from a debit card to a credit card)
that results in a dictionary or object
or null.
This API 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 following are out of scope for this specification:
This section is non-normative.
In order to use the API, the developer needs to provide and keep track
of a number of key pieces of information. These bits of information are
passed to the PaymentRequest
constructor as arguments, and
subsequently used to update the payment request being displayed to the
user. Namely, these bits of information are:
PaymentMethodData
s that
represents the payment methods that the site supports (e.g., "we
support card-based payments, but only Visa and MasterCard credit
cards.").
PaymentDetailsInit
dictionary. This includes total cost, and
optionally a list of goods or services being purchased, for physical
goods, and shipping options. Additionally, it can optionally include
"modifiers" to how payments are made. For example, "if you pay with a
card belonging to network X, it incurs a US$3.00 processing fee".
PaymentOptions
that the site needs to deliver the good or service (e.g., for physical
goods, the merchant will typically need a physical address to ship to.
For digital goods, an email will usually suffice).
Once a PaymentRequest
is constructed, it's presented to the end
user via the show
()
method. The
show
()
returns a promise that, once the user
confirms request for payment, results in a PaymentResponse
.
When constructing a new PaymentRequest
, a merchant uses the first
argument (methodData) to list the different ways a user can pay for
things (e.g., credit cards, Apple Pay, Google Pay, etc.). More
specifically, the methodData sequence contains
PaymentMethodData
dictionaries containing the payment
method identifiers for the payment methods that the
merchant accepts and any associated payment method specific
data (e.g., which credit card networks are supported).
const methodData = [
{
supportedMethods: "https://example.com/payitforward",
data: {
payItForwardField: "ABC",
},
},
{
supportedMethods: "https://example.com/bobpay",
data: {
merchantIdentifier: "XXXX",
bobPaySpecificField: true,
},
},
];
When constructing a new PaymentRequest
, a merchant uses the
second argument of the constructor (details) to provide the details
of the transaction that the user is being asked to complete. This
includes the total of the order and, optionally, some line items that
can provide a detailed breakdown of what is being paid for.
const details = {
id: "super-store-order-123-12312",
displayItems: [
{
label: "Sub-total",
amount: { currency: "GBP", value: "55.00" },
},
{
label: "Value-Added Tax (VAT)",
amount: { currency: "GBP", value: "5.00" },
},
],
total: {
label: "Total due",
// The total is GBP£65.00 here because we need to
// add shipping (below). The selected shipping
// costs GBP£5.00.
amount: { currency: "GBP", value: "65.00" },
},
};
Here we see an example of how to add two shipping options to the details.
const shippingOptions = [
{
id: "standard",
// Shipping by truck, 2 days
label: "🚛 Envío por camión (2 dias)",
amount: { currency: "EUR", value: "5.00" },
selected: true,
},
{
id: "drone",
// Drone shipping, 2 hours
label: "🚀 Drone Express (2 horas)",
amount: { currency: "EUR", value: "25.00" }
},
];
Object.assign(details, { shippingOptions });
Here we see how to add a processing fee for using a card on a particular network. Notice that it requires recalculating the total.
// Certain cards incur a $3.00 processing fee.
const cardFee = {
label: "Card processing fee",
amount: { currency: "AUD", value: "3.00" },
};
// Modifiers apply when the user chooses to pay with
// a card.
const modifiers = [
{
additionalDisplayItems: [cardFee],
supportedMethods: "https://example.com/cardpay",
total: {
label: "Total due",
amount: { currency: "AUD", value: "68.00" },
},
data: {
supportedNetworks: networks,
},
},
];
Object.assign(details, { modifiers });
Some financial transactions require a user to provide specific
information in order for a merchant to fulfill a purchase (e.g., the
user's shipping address, in case a physical good needs to be
shipped). To request this information, a merchant can pass a third
optional argument (options) to the
PaymentRequest
constructor indicating what information they
require. When the payment request is shown, the user agent will
request this information from the end user and return it to the
merchant when the user accepts the payment request.
const options = {
requestPayerEmail: false,
requestPayerName: true,
requestPayerPhone: false,
requestShipping: true,
}
Having gathered all the prerequisite bits of information, we can now
construct a PaymentRequest
and request that the browser present
it to the user:
async function doPaymentRequest() {
try {
const request = new PaymentRequest(methodData, details, options);
// See below for a detailed example of handling these events
request.onshippingaddresschange = ev => ev.updateWith(details);
request.onshippingoptionchange = ev => ev.updateWith(details);
const response = await request.show();
await validateResponse(response);
} catch (err) {
// AbortError, SecurityError
console.error(err);
}
}
async function validateResponse(response) {
try {
const errors = await checkAllValuesAreGood(response);
if (errors.length) {
await response.retry(errors);
return validateResponse(response);
}
await response.complete("success");
} catch (err) {
// Something went wrong...
await response.complete("fail");
}
}
// Must be called as a result of a click
// or some explicit user action.
doPaymentRequest();
Prior to the user accepting to make payment, the site is given an opportunity to update the payment request in response to user input. This can include, for example, providing additional shipping options (or modifying their cost), removing items that cannot ship to a particular address, etc.
const request = new PaymentRequest(methodData, details, options);
// Async update to details
request.onshippingaddresschange = ev => {
ev.updateWith(checkShipping(request));
};
// Sync update to the total
request.onshippingoptionchange = ev => {
// selected shipping option
const { shippingOption } = request;
const newTotal = {
currency: "USD",
label: "Total due",
value: calculateNewTotal(shippingOption),
};
ev.updateWith({ total: newTotal });
};
async function checkShipping(request) {
try {
const { shippingAddress } = request;
await ensureCanShipTo(shippingAddress);
const { shippingOptions, total } = await calculateShipping(shippingAddress);
return { shippingOptions, total };
} catch (err) {
// Shows error to user in the payment sheet.
return { error: `Sorry! we can't ship to your address.` };
}
}
A developer can use the
shippingAddressErrors
member of the
PaymentDetailsUpdate
dictionary to indicate that there are
validation errors with specific attributes of a ContactAddress
.
The shippingAddressErrors
member is a
AddressErrors
dictionary, whose members specifically demarcate
the fields of a physical address that are erroneous while also
providing helpful error messages to be displayed to the end user.
request.onshippingaddresschange = ev => {
ev.updateWith(validateAddress(request.shippingAddress));
};
function validateAddress(shippingAddress) {
const error = "Can't ship to this address.";
const shippingAddressErrors = {
city: "FarmVille is not a real place.",
postalCode: "Unknown postal code for your country.",
};
// Empty shippingOptions implies that we can't ship
// to this address.
const shippingOptions = [];
return { error, shippingAddressErrors, shippingOptions };
}
It's expected that data in a PaymentResponse
will be POSTed back
to a server for processing. To make this as easy as possible,
PaymentResponse
can use the default toJSON steps (i.e.,
.toJSON()
) to serializes the object directly into JSON. This makes
it trivial to POST the resulting JSON back to a server using the
Fetch Standard:
async function doPaymentRequest() {
const payRequest = new PaymentRequest(methodData, details);
const payResponse = await payRequest.show();
let result = "";
try {
const httpResponse = await fetch("/process-payment", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: payResponse.toJSON(),
});
result = httpResponse.ok ? "success" : "fail";
} catch (err) {
console.error(err);
result = "fail";
}
await payResponse.complete(result);
}
doPaymentRequest();
To indicate that a cross-origin iframe
is allowed to invoke the
payment request API, the allow
attribute along with the
"payment" keyword can be specified on the iframe
element.
<iframe
src="https://cross-origin.example"
allow="payment">
</iframe>
If the iframe
will be navigated across multiple origins that
support the Payment Request API, then one can set allow
to
"payment *"
. The Permissions Policy specification provides
further details and examples.
WebIDL[SecureContext, Exposed=Window]
interface PaymentRequest
: EventTarget {
constructor
(
sequence<PaymentMethodData
> methodData,
PaymentDetailsInit
details,
optional PaymentOptions
options = {}
);
[NewObject]
Promise<PaymentResponse
> show
(optional Promise<PaymentDetailsUpdate
> detailsPromise);
[NewObject]
Promise<undefined> abort
();
[NewObject]
Promise<boolean> canMakePayment
();
readonly attribute DOMString id
;
readonly attribute ContactAddress? shippingAddress
;
readonly attribute DOMString? shippingOption
;
readonly attribute PaymentShippingType
? shippingType
;
attribute EventHandler onshippingaddresschange
;
attribute EventHandler onshippingoptionchange
;
attribute EventHandler onpaymentmethodchange
;
};
A developer creates a PaymentRequest
to make a payment request.
This is typically associated with the user initiating a payment
process (e.g., by activating a "Buy," "Purchase," or "Checkout"
button on a web site, selecting a "Power Up" in an interactive game,
or paying at a kiosk in a parking structure). The PaymentRequest
allows developers to exchange information with the user agent
while the user is providing input (up to the point of user approval
or denial of the payment request).
The shippingAddress
,
shippingOption
, and
shippingType
attributes are populated during
processing if the requestShipping
member is set.
A request's payment-relevant browsing context is that
PaymentRequest
's relevant global object's browsing context's
top-level browsing context. Every payment-relevant browsing
context has a payment request is showing boolean, which
prevents showing more than one payment UI at a time.
The payment request is showing boolean simply prevents more than one payment UI being shown in a single browser tab. However, a payment handler can restrict the user agent to showing only one payment UI across all browser windows and tabs. Other payment handlers might allow showing a payment UI across disparate browser tabs.
The PaymentRequest
is constructed using the supplied sequence of
PaymentMethodData
methodData including any payment
method specific data
, the
PaymentDetailsInit
details, and the PaymentOptions
options.
The PaymentRequest(methodData,
details, options)
constructor MUST act as follows:
Document
is not allowed to use the "payment"
permission, then throw a "SecurityError
"
DOMException
.
TypeError
, optionally informing the
developer that at least one payment method is required.
supportedMethods
. If it
returns false, then throw a RangeError
exception.
Optionally, inform the developer that the payment method
identifier is invalid.
supportedMethods
with
basic URL parser:
supportedMethods
.
RangeError
DOMException
optionally informing the
developer that this payment method identifier is a
duplicate.
data
member of
paymentMethod is missing, let serializedData be null.
Otherwise, let serializedData be the result of serialize
paymentMethod.data
into a JSON
string. Rethrow any exceptions.
supportedMethods
specifies an additional data type:
Let idl be the result of converting object to an IDL value of the additional data type. Rethrow any exceptions.
Run the steps to validate payment method data,
if any, from the specification that defines the
paymentMethod.supportedMethods
on object. Rethrow any exceptions.
These step assures that any IDL type conversion and validation errors are caught as early as possible.
supportedMethods
,
serializedData) to serializedMethodData.
total
.amount
.
Rethrow any exceptions.
displayItems
member of details is
present, then for each item in
details.displayItems
:
amount
. Rethrow any exceptions.
requestShipping
member of options is
present and set to true, process shipping options:
sequence
<PaymentShippingOption
>.
shippingOptions
member of
details is present, then:
shippingOptions
:
amount
. Rethrow any exceptions.
id
, then throw a
TypeError
. Optionally, inform the developer that
shipping option IDs must be unique.
id
to seenIDs.
selected
is
true, then set selectedShippingOption to
option.id
.
shippingOptions
to
options.
sequence
<PaymentDetailsModifier
>.
modifiers
member of details
is present, then:
modifiers
.
total
member of
modifier is present, then:
total
.amount
.
Rethrow any exceptions.
additionalDisplayItems
member
of modifier is present, then for each item of
modifier.additionalDisplayItems
:
amount
. Rethrow any
exceptions.
data
member of
modifier is missing, let serializedData be null.
Otherwise, let serializedData be the result of
serialize
modifier.data
into a JSON
string. Rethrow any exceptions.
supportedMethods
,
serializedData) to serializedModifierData.
data
member of
modifier, if it is present.
modifiers
to
modifiers.
PaymentRequest
.
[[handler]]
to null
.
[[options]]
to options.
[[state]]
to
"created".
[[updating]]
to false.
[[details]]
to details.
[[serializedModifierData]]
to
serializedModifierData.
[[serializedMethodData]]
to
serializedMethodData.
[[response]]
to null.
shippingOption
attribute to selectedShippingOption.
shippingAddress
attribute
on request to null.
requestShipping
is set to true,
then set the value of the shippingType
attribute
on request to options.shippingType
. Otherwise,
set it to null.
When getting, the id
attribute returns this
PaymentRequest
's
[[details]]
.id
.
For auditing and reconciliation purposes, a merchant can associate
a unique identifier for each transaction with the
id
attribute.
The show
()
method is called when a developer
wants to begin user interaction for the payment request. The
show
()
method returns 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.
Each payment handler controls what happens when multiple browsing
context simultaneously call the show
()
method.
For instance, some payment handlers will allow multiple payment UIs
to be shown in different browser tabs/windows. Other payment
handlers might only allow a single payment UI to be shown for the
entire user agent.
The show(optional detailsPromise)
method MUST act as
follows:
SecurityError
"
DOMException
.
Document
.
AbortError
" DOMException
.
"visible"
,
then return a promise rejected with an "AbortError
"
DOMException
.
Optionally, if the user agent wishes to disallow the call
to show
()
to protect the user, then return a
promise rejected with a "SecurityError
" DOMException
. For
example, the user agent may limit the rate at which a page
can call show
()
, as described in section
19.
Privacy and Security Considerations.
[[state]]
is not
"created" then return a promise rejected
with an "InvalidStateError
" DOMException
.
[[state]]
to
"closed".
AbortError
"
DOMException
.
[[state]]
to
"interactive".
[[acceptPromise]]
to
acceptPromise.
Optionally:
AbortError
"
DOMException
.
[[state]]
to
"closed".
This allows the user agent to act as if the user had immediately aborted the payment request, at its discretion. For example, in "private browsing" modes or similar, user agents might take advantage of this step.
[[serializedMethodData]]
:
object
.
[[state]]
to
"closed".
[[state]]
to
"closed".
NotSupportedError
"
DOMException
.
Present a user interface that will allow the user to interact with the handlers. The user agent SHOULD prioritize the user's preference when presenting payment methods. The user interface SHOULD be presented using the language and locale-based formatting that matches the document's document element's language, if any, or an appropriate fallback if that is not available.
PaymentRequest
's details
algorithm with detailsPromise, request, and null.
Based on how the detailsPromise settles, the update a
PaymentRequest
's details algorithm
determines how the payment UI behaves. That is, upon
rejection of the detailsPromise, the payment request
aborts. Otherwise, upon fulfillment detailsPromise,
the user agent re-enables the payment request UI and the
payment flow can continue.
[[handler]]
be the payment
handler selected by the end-user.
[[serializedModifierData]]
:
[[handler]]
, then append the second
element of tuple (the serialized method data) to modifiers.
Pass the converted second element in the paymentMethod tuple and modifiers. Optionally, the user agent SHOULD send the appropriate data from request to the user-selected payment handler in order to guide the user through the payment process. This includes the various attributes and other internal slots of request (some MAY be excluded for privacy reasons where appropriate).
Handling of multiple applicable modifiers in the
[[serializedModifierData]]
internal slot
is payment handler specific and beyond the scope of this
specification. Nevertheless, it is RECOMMENDED that payment
handlers use a "last one wins" approach with items in the
[[serializedModifierData]]
list: that is to
say, an item at the end of the list always takes precedence over
any item at the beginning of the list (see example below).
The acceptPromise will later be resolved or rejected by either the user accepts the payment request algorithm or the user aborts the payment request algorithm, which are triggered through interaction with the user interface.
If document stops being fully active while the user interface is being shown, or no longer is by the time this step is reached, then:
The abort
()
method is called if a developer
wishes to tell the user agent to abort the payment request
and to tear down any user interface that might be shown. The
abort
()
can only be called after the
show
()
method has been called (see
states) and before this instance's
[[acceptPromise]]
has been resolved. For
example, developers 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
.
See also the algorithm when the user aborts the payment request.
The abort
()
method MUST act as follows:
[[response]]
is not null, and
request.[[response]]
.[[retryPromise]]
is not null, return a promise rejected with an
"InvalidStateError
" DOMException
.
[[state]]
is not
"interactive" then return a promise rejected
with an "InvalidStateError
" DOMException
.
InvalidStateError
"
DOMException
and abort these steps.
[[state]]
to
"closed".
[[acceptPromise]]
with an
"AbortError
" DOMException
.
The canMakePayment
()
method can be used by the
developer to determine if the user agent has support for one
of the desired payment methods. See
19.8
canMakePayment()
protections.
A true result from canMakePayment
()
does not
imply that the user has a provisioned instrument ready for payment.
The canMakePayment
()
method MUST run the can
make payment algorithm.
A PaymentRequest
's shippingAddress
attribute
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.
A PaymentRequest
's shippingType
attribute is
the type of shipping used to fulfill the transaction. Its value is
either a PaymentShippingType
enum value, or null if none is
provided by the developer during
construction
(see
PaymentOptions
's shippingType
member).
A PaymentRequest
's onshippingaddresschange
attribute is an EventHandler
for a PaymentRequestUpdateEvent
named shippingaddresschange
.
A PaymentRequest
's shippingOption
attribute 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.
A PaymentRequest
's onshippingoptionchange
attribute is an EventHandler
for a PaymentRequestUpdateEvent
named shippingoptionchange
.
A PaymentRequest
's onpaymentmethodchange
attribute is an EventHandler
for a PaymentMethodChangeEvent
named "paymentmethodchange
".
Instances of PaymentRequest
are created with the internal slots in the following table:
Internal Slot | Description (non-normative) |
---|---|
[[serializedMethodData]] |
The methodData supplied to the constructor, but
represented as tuples containing supported methods and a string
or null for data (instead of the original object form).
|
[[serializedModifierData]] |
A list containing the serialized string form of each
data member for each corresponding
item in the sequence
[[details]] .modifier ,
or null if no such member was present.
|
[[details]] |
The current PaymentDetailsBase for the payment request
initially supplied to the constructor and then updated with calls
to updateWith () . Note that all
data members of
PaymentDetailsModifier instances contained in the
modifiers member will be removed, as they
are instead stored in serialized form in the
[[serializedModifierData]] internal slot.
|
[[options]] |
The PaymentOptions supplied to the constructor.
|
[[state]] |
The current state of the payment request, which transitions from:
The state transitions are illustrated in the figure below: show ()
method changes the state to
"interactive". From there, the
abort () method or any other error can send
the state to "closed";
similarly, the user accepts the payment request
algorithm and user aborts the payment request
algorithm will change the state to
"closed".
|
[[updating]] |
True if 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.
|
[[response]] |
Null, or the PaymentResponse instantiated by this
PaymentRequest .
|
[[handler]] |
The Payment Handler associated with this
PaymentRequest . Initialized to null .
|
WebIDLdictionary PaymentMethodData
{
required 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.
supportedMethods
member
data
member
The value of supportedMethods
was changed from array to
string, but the name was left as a plural to maintain compatibility
with existing content on the Web.
WebIDLdictionary PaymentCurrencyAmount
{
required DOMString currency
;
required DOMString value
;
};
A PaymentCurrencyAmount
dictionary is used to supply monetary
amounts.
currency
member
An [ISO4217] well-formed 3-letter alphabetic code (i.e., the numeric codes are not supported). Their canonical form is upper case. However, the set of combinations of currency code for which localized currency symbols are available is implementation dependent.
When displaying a monetary value, it is RECOMMENDED that user agents display the currency code, but it's OPTIONAL for user agents to display a currency symbol. This is because currency symbols can be ambiguous due to use across a number of different currencies (e.g., "$" could mean any of USD, AUD, NZD, CAD, and so on.).
User agents MAY format the display of the
currency
member to adhere to OS
conventions (e.g., for localization purposes).
User agents implementing this specification enforce [ISO4217]'s
3-letter codes format via ECMAScript’s isWellFormedCurrencyCode
abstract operation, which is invoked as part of the check and
canonicalize amount algorithm. When a code does not adhere to
the [ISO4217] defined format, a RangeError
is thrown.
Current implementations will therefore allow the use of well-formed currency codes that are not part of the official [ISO4217] list (e.g., XBT, XRP, etc.). If the provided code is a currency that the browser knows how to display, then an implementation will generally display the appropriate currency symbol in the user interface (e.g., "USD" is shown as U+0024 Dollar Sign ($), "GBP" is shown as U+00A3 Pound Sign (£), "PLN" is shown as U+007A U+0142 Złoty (zł), and the non-standard "XBT" could be shown as U+0243 Latin Capital Letter B with Stroke (Ƀ)).
Efforts are underway at ISO to account for digital currencies, which may result in an update to the [ISO4217] registry or an entirely new registry. The community expects this will resolve ambiguities that have crept in through the use of non-standard 3-letter codes; for example, does "BTC" refer to Bitcoin or to a future Bhutan currency? At the time of publication, it remains unclear what form this evolution will take, or even the time frame in which the work will be completed. The W3C Web Payments Working Group is liaising with ISO so that, in the future, revisions to this specification remain compatible with relevant ISO registries.
value
member
{
"currency": "OMR",
"value": "1.234"
}
A JavaScript string is a valid decimal monetary value if it consists of the following code points in the given order:
^-?[0-9]+(\.[0-9]+)?$
To check and canonicalize amount given a
PaymentCurrencyAmount
amount, run the following steps:
currency
)
is false, then throw a RangeError
exception, optionally informing
the developer that the currency is invalid.
value
is not a valid
decimal monetary value, throw a TypeError
, optionally
informing the developer that the currency is invalid.
currency
to the result of
ASCII uppercase amount.currency
.
To check and canonicalize total amount given a
PaymentCurrencyAmount
amount, run the
following steps:
value
is U+002D (-), then throw a
TypeError
optionally informing the developer that a total's value
can't be a negative number.
WebIDLdictionary PaymentDetailsBase
{
sequence<PaymentItem
> displayItems
;
sequence<PaymentShippingOption
> shippingOptions
;
sequence<PaymentDetailsModifier
> modifiers
;
};
displayItems
member
PaymentItem
dictionaries contains line items for
the payment request that the user agent MAY display.
shippingOptions
member
A sequence containing the different shipping options for the user to choose from.
If an item in the sequence has the
selected
member 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. If more than one item
in the sequence has selected
set to
true, then the user agent selects the last one in the
sequence.
The shippingOptions
member is only used if
the PaymentRequest
was constructed with PaymentOptions
and requestShipping
set to true.
modifiers
member
PaymentDetailsModifier
dictionaries that contains
modifiers for particular payment method identifiers. For example,
it allows you to adjust the total amount based on payment method.
WebIDLdictionary PaymentDetailsInit
: PaymentDetailsBase
{
DOMString id
;
required PaymentItem
total
;
};
In addition to the members inherited from the PaymentDetailsBase
dictionary, the following members are part of the
PaymentDetailsInit
dictionary:
id
member
total
member
PaymentItem
containing a non-negative total amount for the
payment request.
WebIDLdictionary PaymentDetailsUpdate
: PaymentDetailsBase
{
DOMString error
;
PaymentItem
total
;
AddressErrors
shippingAddressErrors
;
PayerErrors
payerErrors
;
object paymentMethodErrors
;
};
The PaymentDetailsUpdate
dictionary is used to update the payment
request using updateWith
()
.
In addition to the members inherited from the PaymentDetailsBase
dictionary, the following members are part of the
PaymentDetailsUpdate
dictionary:
error
member
updateWith
()
, the
PaymentDetailsUpdate
can contain a message in the
error
member that will be displayed to the
user if the PaymentDetailsUpdate
indicates that there are no
valid shippingOptions
(and the
PaymentRequest
was constructed with the
requestShipping
option set to true).
total
member
PaymentItem
containing a non-negative amount
.
Algorithms in this specification that accept a
PaymentDetailsUpdate
dictionary will throw if the
total
.amount
.value
is a negative number.
shippingAddressErrors
member
payerErrors
member
paymentMethodErrors
member
Payment method specific errors.
WebIDLdictionary PaymentDetailsModifier
{
required DOMString supportedMethods
;
PaymentItem
total
;
sequence<PaymentItem
> additionalDisplayItems
;
object data
;
};
The PaymentDetailsModifier
dictionary provides details that modify
the PaymentDetailsBase
based on a payment method identifier.
It contains the following members:
supportedMethods
member
PaymentDetailsModifier
only apply if the user selects this
payment method.
total
member
PaymentItem
value that overrides the
total
member in the PaymentDetailsInit
dictionary for the payment method identifiers of the
supportedMethods
member.
additionalDisplayItems
member
PaymentItem
dictionaries provides additional
display items that are appended to the
displayItems
member in the
PaymentDetailsBase
dictionary for the payment method
identifiers in the supportedMethods
member. This member is commonly used to add a discount or surcharge
line item indicating the reason for the different
total
amount for the selected payment
method that the user agent MAY display.
It is the developer's responsibility to verify that the
total
amount is the sum of the
displayItems
and the
additionalDisplayItems
.
data
member
WebIDLenum PaymentShippingType
{
"shipping
",
"delivery
",
"pickup
"
};
shipping
"
delivery
"
pickup
"
WebIDLdictionary PaymentOptions
{
boolean requestPayerName
= false;
boolean requestBillingAddress
= false;
boolean requestPayerEmail
= false;
boolean requestPayerPhone
= false;
boolean requestShipping
= false;
PaymentShippingType
shippingType
= "shipping";
};
The PaymentOptions
dictionary is passed to the PaymentRequest
constructor and provides information about the options desired for the
payment request.
requestBillingAddress
member
PaymentMethodChangeEvent
's
methodDetails
. A merchant can use this
information to, for example, calculate tax in certain jurisdictions
and update the displayed total. See below for privacy considerations
regarding exposing user information.
requestPayerName
member
requestPayerEmail
member
requestPayerPhone
member
requestShipping
member
shippingType
member
PaymentShippingType
enum value. Some transactions require an
address for delivery but the term "shipping"
isn't appropriate. For example, "pizza delivery" not "pizza shipping"
and "laundry pickup" not "laundry shipping". If
requestShipping
is set to true, then the
shippingType
member can influence the way the
user agent presents the user interface for gathering the
shipping address.
The shippingType
member only affects the user
interface for the payment request.
WebIDLdictionary PaymentItem
{
required DOMString label
;
required PaymentCurrencyAmount
amount
;
boolean pending
= false;
};
A sequence of one or more PaymentItem
dictionaries is included in
the PaymentDetailsBase
dictionary to indicate what the payment
request is for and the value asked for.
label
member
amount
member
PaymentCurrencyAmount
containing the monetary amount for the
item.
pending
member
amount
member is not final. This is commonly used to show items such as
shipping or tax amounts that depend upon selection of shipping
address or shipping option. User agents MAY indicate pending
fields in the user interface for the payment request.
WebIDLdictionary PaymentCompleteDetails
{
object? data
= null;
};
The PaymentCompleteDetails
dictionary provides additional
information from the merchant website to the payment handler when the
payment request completes.
The PaymentCompleteDetails
dictionary contains the following
members:
data
member
PaymentResponse
associated payment method. If supplied,
it will be serialize.
WebIDLenum PaymentComplete
{
"fail
",
"success
",
"unknown
"
};
fail
"
success
"
unknown
"
WebIDLdictionary PaymentShippingOption
{
required DOMString id
;
required DOMString label
;
required PaymentCurrencyAmount
amount
;
boolean selected
= false;
};
The PaymentShippingOption
dictionary has members describing a
shipping option. Developers can provide the user with one or more
shipping options by calling the
updateWith
()
method in response to a
change event.
id
member
PaymentShippingOption
.
It MUST be unique for a given PaymentRequest
.
label
member
amount
member
PaymentCurrencyAmount
containing the monetary amount for the
item.
selected
member
PaymentShippingOption
in a sequence. User agents SHOULD
display this option by default in the user interface.
WebIDL[SecureContext, Exposed=Window]
interface PaymentResponse
: EventTarget {
[Default] object toJSON();
readonly attribute DOMString requestId
;
readonly attribute DOMString methodName
;
readonly attribute object details
;
readonly attribute ContactAddress? shippingAddress
;
readonly attribute DOMString? shippingOption
;
readonly attribute DOMString? payerName
;
readonly attribute DOMString? payerEmail
;
readonly attribute DOMString? payerPhone
;
[NewObject]
Promise<undefined> complete
(
optional PaymentComplete
result = "unknown",
optional PaymentCompleteDetails
details = {}
);
[NewObject]
Promise<undefined> retry
(optional PaymentValidationErrors
errorFields = {});
attribute EventHandler onpayerdetailchange
;
};
A PaymentResponse
is returned when a user has selected a payment
method and approved a payment request.
The retry(errorFields)
method
MUST act as follows:
[[request]]
.
Document
.
AbortError
" DOMException
.
[[complete]]
is true, return
a promise rejected with an "InvalidStateError
"
DOMException
.
[[retryPromise]]
is not null,
return a promise rejected with an "InvalidStateError
"
DOMException
.
[[state]]
to
"interactive".
[[retryPromise]]
to
retryPromise.
[[options]]
.requestPayerName
is false, and
errorFields.payer
.name
is present.
[[options]]
.requestPayerEmail
is false, and
errorFields.payer
.email
is present.
[[options]]
.requestPayerPhone
is false, and
errorFields.payer
.phone
is present.
[[options]]
.requestShipping
is false, and
errorFields.shippingAddress
is
present.
paymentMethod
member was passed, and if required by the specification that
defines response.methodName
, then
convert errorFields's
paymentMethod
member to an IDL value
of the type specified there. Otherwise, convert to object
.
error
member is passed,
present the error in the user agent's UI. In the case where the
value of a member is the empty string, the user agent MAY
substitute a value with a suitable error message.
[[retryPromise]]
to null.
The retryPromise will later be resolved by the user accepts the payment request algorithm, or rejected by either the user aborts the payment request algorithm or abort the update.
WebIDLdictionary PaymentValidationErrors
{
PayerErrors
payer
;
AddressErrors
shippingAddress
;
DOMString error
;
object paymentMethod
;
};
payer
member
shippingAddress
member
PaymentResponse
's
shippingAddress
.
error
member
error
member on its own to give a
general overview of validation issues, or it can be passed in
combination with other members of the PaymentValidationErrors
dictionary.
paymentMethod
member
WebIDLdictionary PayerErrors
{
DOMString email
;
DOMString name
;
DOMString phone
;
};
The PayerErrors
is used to represent validation errors with one
or more payer details.
Payer details are any of the payer's name, payer's phone number, and payer's email.
email
member
PaymentResponse
's
payerEmail
attribute's value.
name
member
PaymentResponse
's
payerName
attribute's value.
phone
member
PaymentResponse
's
payerPhone
attribute's value.
The payment method identifier for the payment method that the user selected to fulfill the transaction.
An object
or dictionary generated by a payment
method that a merchant can use to process or validate a
transaction (depending on the payment method).
If the requestShipping
member 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.
If the requestShipping
member was set to true in
the PaymentOptions
passed to the PaymentRequest
constructor,
then shippingOption
will be the
id
attribute of the selected shipping
option.
If the requestPayerName
member was set to true in
the PaymentOptions
passed to the PaymentRequest
constructor,
then payerName
will be the name provided by the
user.
If the requestPayerEmail
member was set to true in
the PaymentOptions
passed to the PaymentRequest
constructor,
then payerEmail
will be the email address chosen
by the user.
If the requestPayerPhone
member was set to true in
the PaymentOptions
passed to the PaymentRequest
constructor,
then payerPhone
will be the phone number chosen
by the user.
The corresponding payment request id
that spawned
this payment response.
The complete
()
method is 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 payment interaction is over (and SHOULD cause any remaining
user interface to be closed).
After the payment request has been accepted and the
PaymentResponse
returned to the caller, but before the caller
calls complete
()
, the payment request user
interface remains in a pending state. At this point the user
interface SHOULD NOT offer a cancel command because acceptance of the
payment request has been returned. However, if something goes wrong
and the developer never calls complete
()
then the
user interface is blocked.
For this reason, implementations MAY impose a timeout for developers
to call complete
()
. If the timeout expires then
the implementation will behave as if complete
()
was called with no arguments.
The complete
()
method MUST act as follows:
[[complete]]
is true, return
a promise rejected with an "InvalidStateError
"
DOMException
.
[[retryPromise]]
is not null,
return a promise rejected with an "InvalidStateError
"
DOMException
.
data
into a JSON string.
methodName
:
JSON
's parse
()
with serializedData.
methodName
.
methodName
, validate the members
of idl. If a member's value is invalid, return a promise
rejected with a TypeError
.
[[complete]]
to true.
Allows a developer to handle "payerdetailchange
" events.
Instances of PaymentResponse
are created with the internal slots in the following table:
Internal Slot | Description (non-normative) |
---|---|
[[complete]] |
Is true if the request for payment has completed (i.e.,
complete () was called, or there was a fatal
error that made the response not longer usable), or false
otherwise.
|
[[request]] |
The PaymentRequest instance that instantiated this
PaymentResponse .
|
[[retryPromise]] |
Null, or a Promise that resolves when a user accepts the
payment request or rejects if the user aborts the payment
request.
|
The PaymentRequest
interface allows a merchant to request from the
user physical addresses for the purposes of
shipping and/or billing. A shipping address and billing
address are physical addresses.
WebIDLdictionary AddressErrors
{
DOMString addressLine
;
DOMString city
;
DOMString country
;
DOMString dependentLocality
;
DOMString organization
;
DOMString phone
;
DOMString postalCode
;
DOMString recipient
;
DOMString region
;
DOMString sortingCode
;
};
The members of the AddressErrors
dictionary represent validation
errors with specific parts of a physical address. Each dictionary
member has a dual function: firstly, its presence denotes that a
particular part of an address is suffering from a validation error.
Secondly, the string value allows the developer to describe the
validation error (and possibly how the end user can fix the error).
Developers need to be aware that users might not have the ability to fix certain parts of an address. As such, they need to be mindful not to ask the user to fix things they might not have control over.
addressLine
member
ContactAddress
's
addressLine
attribute's value.
city
member
ContactAddress
's city
attribute's value.
country
member
ContactAddress
's
country
attribute's value.
dependentLocality
member
ContactAddress
's
dependentLocality
attribute's value.
organization
member
ContactAddress
's
organization
attribute's value.
phone
member
ContactAddress
's
phone
attribute's value.
postalCode
member
ContactAddress
's
postalCode
attribute's value.
recipient
member
ContactAddress
's
addressLine
attribute's value.
region
member
ContactAddress
's
region
attribute's value.
sortingCode
member
ContactAddress
's
sortingCode
attribute's value.
This specification defines a policy-controlled feature identified by the string "payment" [permissions-policy]. Its default allowlist is 'self'.
This section is non-normative.
Event name | Interface | Dispatched when… | Target |
---|---|---|---|
shippingaddresschange
|
PaymentRequestUpdateEvent
|
The user provides a new shipping address. |
PaymentRequest
|
shippingoptionchange
|
PaymentRequestUpdateEvent
|
The user chooses a new shipping option. |
PaymentRequest
|
payerdetailchange
|
PaymentRequestUpdateEvent
|
The user changes the payer name, the payer email, or the payer phone (see payer detail changed algorithm). |
PaymentResponse
|
paymentmethodchange
|
PaymentMethodChangeEvent
|
The user chooses a different payment method within a payment handler. |
PaymentRequest
|
WebIDL[SecureContext, Exposed=Window]
interface PaymentMethodChangeEvent
: PaymentRequestUpdateEvent
{
constructor
(DOMString type, optional PaymentMethodChangeEventInit
eventInitDict = {});
readonly attribute DOMString methodName
;
readonly attribute object? methodDetails
;
};
When getting, returns the value it was initialized with. See
methodDetails
member of
PaymentMethodChangeEventInit
for more information.
When getting, returns the value it was initialized with. See
methodName
member of
PaymentMethodChangeEventInit
for more information.
WebIDLdictionary PaymentMethodChangeEventInit
: PaymentRequestUpdateEventInit
{
DOMString methodName
= "";
object? methodDetails
= null;
};
methodName
member
methodDetails
member
WebIDL[SecureContext, Exposed=Window]
interface PaymentRequestUpdateEvent
: Event {
constructor
(DOMString type, optional PaymentRequestUpdateEventInit
eventInitDict = {});
undefined updateWith
(Promise<PaymentDetailsUpdate
> detailsPromise);
};
The PaymentRequestUpdateEvent
enables developers to update the
details of the payment request in response to a user interaction.
The PaymentRequestUpdateEvent
's
constructor
(type, eventInitDict)
MUST
act as follows:
PaymentRequestUpdateEvent
with
type and eventInitDict.
[[waitForUpdate]]
to
false.
The updateWith
()
with
detailsPromise method MUST act as follows:
isTrusted
attribute is false, then
throw an "InvalidStateError
" DOMException
.
[[waitForUpdate]]
is
true, then throw an "InvalidStateError
"
DOMException
.
PaymentResponse
, let request be event's
target's [[request]]
.
PaymentRequest
.
[[state]]
is not
"interactive", then throw an
"InvalidStateError
" DOMException
.
[[updating]]
is true, then
throw an "InvalidStateError
" DOMException
.
[[waitForUpdate]]
to
true.
methodName
attribute, set pmi to the methodName
attribute's value.
PaymentRequest
's details
algorithm with detailsPromise, request, and pmi.
Instances of PaymentRequestUpdateEvent
are created with the
internal slots in the following table:
Internal Slot | Description (non-normative) |
---|---|
[[waitForUpdate]] |
A boolean indicating whether an
updateWith () -initiated update is
currently in progress.
|
WebIDLdictionary PaymentRequestUpdateEventInit
: EventInit {};
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.
The can make payment algorithm checks if the user
agent supports making payment with the payment methods
with which the PaymentRequest
was constructed.
PaymentRequest
object on
which the method was called.
[[state]]
is not
"created", then return a promise rejected
with an "InvalidStateError
" DOMException
.
NotAllowedError
" DOMException
.
This allows user agents to apply heuristics to detect and prevent
abuse of the calling method for fingerprinting purposes, such as
creating PaymentRequest
objects with a variety of supported
payment methods and triggering the can make payment
algorithm on them one after the other. For example, a user
agent may restrict the number of successful calls that can be
made based on the top-level browsing context or the time
period in which those calls were made.
[[serializedMethodData]]
:
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.
The redactList limits the amount of personal information about the recipient that the API shares with the merchant.
For merchants, the resulting ContactAddress
object
provides enough information to, for example, calculate
shipping costs, but, in most cases, not enough information
to physically locate and uniquely identify the recipient.
Unfortunately, even with the redactList, recipient anonymity cannot be assured. This is because in some countries postal codes are so fine-grained that they can uniquely identify a recipient.
shippingAddress
to
address.
shippingaddresschange
".
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.
shippingOption
attribute on
request to the id
string of the
PaymentShippingOption
provided by the user.
shippingoptionchange
".
A payment handler MAY run the payment method changed algorithm
when the user changes payment method with methodDetails,
which is a dictionary or an object
or null, and a
methodName, which is a DOMString that represents the payment
method identifier of the payment handler the user is
interacting with.
When the user selects or changes a payment method (e.g., a credit
card), the PaymentMethodChangeEvent
includes redacted billing
address information for the purpose of performing tax calculations.
Redacted attributes include, but are not limited to, address line, dependent locality,
organization, phone number,
and recipient.
PaymentRequest
object
that the user is interacting with.
[[updating]]
is false.
Only one update can take place at a time.
[[state]]
is
"interactive".
paymentmethodchange
" at
request using PaymentMethodChangeEvent
, with its
methodName
attribute initialized
to methodName, and its
methodDetails
attribute
initialized to methodDetails.
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:
[[updating]]
is false. Only
one update can take place at a time.
[[state]]
is
"interactive".
PaymentRequestUpdateEvent
interface.
type
attribute to name.
[[waitForUpdate]]
is
true, disable any part of the user interface that could cause another
update event to be fired.
[[waitForUpdate]]
to true.
The user agent MUST run the payer detail changed algorithm when the user changes the payer name, or the payer email, or the payer phone in the user interface:
PaymentRequest
object
that the user is interacting with.
[[response]]
is null, return.
[[response]]
.
[[updating]]
is false.
[[state]]
is
"interactive".
[[options]]
.
requestPayerName
is true:
payerName
attribute to
payer name.
requestPayerEmail
is true:
payerEmail
to payer
email.
requestPayerPhone
is true:
payerPhone
to payer
phone.
PaymentRequestUpdateEvent
.
type
attribute to
"payerdetailchange
".
[[waitForUpdate]]
is
true, disable any part of the user interface that could cause
another change to the payer details to be fired.
[[waitForUpdate]]
to true.
The user accepts the payment request algorithm runs when the user accepts the payment request and confirms that they want to pay. It MUST queue a task on the user interaction task source to perform the following steps:
PaymentRequest
object
that the user is interacting with.
[[updating]]
is true, then
terminate this algorithm and take no further action. The user
agent user interface SHOULD ensure that this never occurs.
[[state]]
is not
"interactive", 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. The
user agent SHOULD ensure that this never occurs.
[[response]]
is not null, false
otherwise.
[[response]]
if isRetry is true, or a
new PaymentResponse
otherwise.
[[request]]
to request.
[[retryPromise]]
to null.
[[complete]]
to false.
requestId
attribute value of
response to the value of
request.[[details]]
.id
.
[[response]]
to response.
[[handler]]
.
methodName
attribute value of
response to the payment method identifier of handler.
details
attribute value of response
to an object resulting from running the handler's steps to
respond to a payment request.
requestShipping
value of
request.[[options]]
is false, then set the
shippingAddress
attribute value of response to
null. Otherwise:
shippingAddress
attribute value
of response to shippingAddress.
shippingAddress
attribute value
of request to shippingAddress.
requestShipping
value of
request.[[options]]
is true, then set the
shippingOption
attribute of response to the
value of the shippingOption
attribute of
request. Otherwise, set it to null.
requestPayerName
value of
request.[[options]]
is true, then set the
payerName
attribute of response to the payer's
name provided by the user, or to null if none was provided.
Otherwise, set it to null.
requestPayerEmail
value of
request.[[options]]
is true, then set the
payerEmail
attribute of response to the payer's
email address provided by the user, or to null if none was provided.
Otherwise, set it to null.
requestPayerPhone
value of
request.[[options]]
is true, then set the
payerPhone
attribute of response to the payer's
phone number provided by the user, or to null if none was provided.
When setting the payerPhone
value, the user agent
SHOULD format the phone number to adhere to [E.164].
[[state]]
to
"closed".
[[retryPromise]]
with undefined.
Otherwise, resolve request.[[acceptPromise]]
with response.
The user aborts the payment request algorithm runs when the user aborts the payment request through the currently interactive user interface. It MUST queue a task on the user interaction task source to perform the following steps:
PaymentRequest
object
that the user is interacting with.
[[state]]
is not
"interactive", then terminate this algorithm and
take no further action. The user agent user interface SHOULD
ensure that this never occurs.
[[state]]
to
"closed".
AbortError
" DOMException
.
[[response]]
.
[[complete]]
to true.
[[retryPromise]]
is
not null.
[[retryPromise]]
with
error.
[[acceptPromise]]
with error.
The update a PaymentRequest
's details
algorithm takes a PaymentDetailsUpdate
detailsPromise, a
PaymentRequest
request, and pmi that is either a DOMString or
null (a payment method identifier). The steps are conditional
on the detailsPromise settling. If detailsPromise never settles
then the payment request is blocked. The user agent SHOULD provide
the user with a means to abort a payment request. Implementations MAY
choose to implement a timeout for pending updates if detailsPromise
doesn't settle in a reasonable amount of time.
In the case where a timeout occurs, or the user manually aborts, or the payment handler decides to abort this particular payment, the user agent MUST run the user aborts the payment request algorithm.
[[updating]]
to true.
AbortError
"
DOMException
.
PaymentDetailsUpdate
dictionary. If this throw
an exception, abort the update with request and with the
thrown exception.
sequence
<PaymentShippingOption
>.
total
member of details
is present, then:
total
.amount
.
If an exception is thrown, then abort the update
with request and that exception.
displayItems
member of
details is present, then for each item in
details.displayItems
:
amount
. If an exception is
thrown, then abort the update with request and
that exception.
shippingOptions
member of
details is present, and
request.[[options]]
.requestShipping
is true, then:
shippingOptions
:
amount
. If an
exception is thrown, then abort the update
with request and that exception.
TypeError
.
id
to
seenIDs.
selected
is
true, then set selectedShippingOption to
option.id
.
modifiers
member of
details is present, then:
modifiers
.
PaymentDetailsModifier
modifier in
modifiers:
supportedMethods
.
If it returns false, then abort the update
with request and a RangeError
exception.
Optionally, inform the developer that the payment
method identifier is invalid.
total
member of
modifier is present, then:
total
.amount
.
If an exception is thrown, then abort the
update with request and that exception.
additionalDisplayItems
member of modifier is present, then for each
PaymentItem
item in
modifier.additionalDisplayItems
:
amount
. If an exception
is thrown, then abort the update with
request and that exception.
data
member of
modifier is missing, let serializedData be null.
Otherwise, let serializedData be the result of
serialize
modifier.data
into a
JSON string. If it throws an exception, then abort
the update with request and that exception.
data
member
of modifier, if it is present.
paymentMethodErrors
member is
present and identifier is not null:
paymentMethodErrors
to an IDL value.
paymentMethodErrors
.
PaymentRequest
using the new details:
total
member of details
is present, then:
[[details]]
.total
to details.total
.
displayItems
member of
details is present, then:
[[details]]
.displayItems
to details.displayItems
.
shippingOptions
member of
details is present, and
request.[[options]]
.requestShipping
is true, then:
[[details]]
.shippingOptions
to shippingOptions.
shippingOption
attribute to
selectedShippingOption.
modifiers
member of
details is present, then:
[[details]]
.modifiers
to details.modifiers
.
[[serializedModifierData]]
to serializedModifierData.
If
request.[[options]]
.requestShipping
is true, and
request.[[details]]
.shippingOptions
is empty, then the developer has signified that there are
no valid shipping options for the currently-chosen
shipping address (given by request's
shippingAddress
).
In this case, the user agent SHOULD display an error
indicating this, and MAY indicate that the
currently-chosen shipping address is invalid in some way.
The user agent SHOULD use the
error
member of details, if it
is present, to give more information about why there are
no valid shipping options for that address.
Further, if
details["shippingAddressErrors
"]
member is present, the user agent SHOULD display an error
specifically for each erroneous field of the shipping
address. This is done by matching each present member of
the AddressErrors
to a corresponding input field in
the shown user interface.
Similarly, if details["payerErrors
"] member is
present and request.[[options]]
's
requestPayerName
,
requestPayerEmail
, or
requestPayerPhone
is true, then
display an error specifically for each erroneous field.
Likewise, if
details.paymentMethodErrors
is
present, then display errors specifically for each
erroneous input field for the particular payment method.
[[updating]]
to false.
To abort the update with a
PaymentRequest
request and exception exception:
[[state]]
to
"closed".
[[response]]
.
[[complete]]
to
true.
[[retryPromise]]
is not null.
[[retryPromise]]
with exception.
[[acceptPromise]]
with
exception.
[[updating]]
to false.
Abort the update runs when there is a fatal error updating the payment request, such as the supplied detailsPromise rejecting, or its fulfillment value containing invalid data. This would potentially leave the payment request in an inconsistent state since the developer hasn't successfully handled the change event.
Consequently, the PaymentRequest
moves to a
"closed" state. The error is signaled to the
developer through the rejection of the
[[acceptPromise]]
, i.e., the promise returned by
show
()
.
Similarly, abort the update occurring during
retry
()
causes the
[[retryPromise]]
to reject, and the
corresponding PaymentResponse
's
[[complete]]
internal slot will be set to
true (i.e., it can no longer be used).
This section is non-normative.
To help ensure that users do not inadvertently share sensitive
credentials with an origin, this API requires that PaymentRequest's
show
()
method be invoked while the relevant
Window
has transient activation (e.g., via a click or press).
To avoid a confusing user experience, this specification limits the
user agent to displaying one at a time via the
show
()
method. In addition, the user agent can
limit the rate at which a page can call show
()
.
This section is non-normative.
The API defined in this specification is only exposed in a secure context - see also the Secure Contexts specification for more details. In practice, this means that this API is only available over HTTPS. This is to limit the possibility of payment method data (e.g., credit card numbers) being sent in the clear.
This section is non-normative.
It is common for merchants and other payees to delegate checkout and
other e-commerce activities to payment service providers through an
iframe. This API supports payee-authorized cross-origin
iframes through [HTML]'s allow
attribute.
Payment handlers have access to both the origin that hosts the
iframe and the origin of the iframe content (where the
PaymentRequest
initiates).
This section is non-normative.
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.
This section is non-normative.
For security reasons, a user agent can limit matching (in
show
()
and canMakePayment
()
) to
payment handlers from the same origin as a URL payment method
identifier.
Payment method owners establish the privacy policies for how user data collected for the payment method may be used. Payment Request API sets a clear expectation that data will be used for the purposes of completing a transaction, and user experiences associated with this API convey that intention. It is the responsibility of the payee to ensure that any data usage conforms to payment method policies. For any permitted usage beyond completion of the transaction, the payee should clearly communicate that usage to the user.
The user agent MUST NOT share information about the user with a developer (e.g., the shipping address) without user consent.
In particular, the PaymentMethodData
's data
and PaymentResponse
's details
members allow
for the arbitrary exchange of data. In light of the wide range of
data models used by existing payment methods, prescribing data
specifics in this API would limit its usefulness. The
details
member carries data from the payment
handler, whether Web-based (as defined by the Payment Handler API)
or proprietary. The user agent MUST NOT support payment handlers
unless they include adequate user consent mechanisms (such as
awareness of parties to the transaction and mechanisms for
demonstrating the intention to share data).
The user agent MUST NOT share the values of the
displayItems
member or
additionalDisplayItems
member for any
purpose other than to facilitate completion of the transaction.
The PaymentMethodChangeEvent
enables the payee to update the
displayed total based on information specific to a selected
payment method. For example, the billing address associated
with a selected payment method might affect the tax
computation (e.g., VAT), and it is desirable that the user interface
accurately display the total before the payer completes the
transaction. At the same time, it is desirable to share as little
information as possible prior to completion of the payment.
Therefore, when a payment method defines the steps for when
a user changes payment method, it is important to minimize the
data shared via the PaymentMethodChangeEvent
's
methodDetails
attribute. Requirements
and approaches for minimizing shared data are likely to vary by
payment method and might include:
shippingAddress
.
PaymentResponse
.details). The
payee might provide these instructions via
PaymentMethodData
.data, enabling a payment method
definition to evolve without requiring changes to the current API.
Where sharing of privacy-sensitive information might not be obvious to users (e.g., when changing payment methods), it is RECOMMENDED that user agents inform the user of exactly what information is being shared with a merchant.
The canMakePayment
()
method provides feature
detection for different payment methods. It may become a
fingerprinting vector if in the future, a large number of payment
methods are available. User agents are expected to protect the user
from abuse of the method. For example, user agents can reduce user
fingerprinting by:
For rate-limiting the user agent might look at repeated calls from:
iframe
or popup window.
These rate-limiting techniques intend to increase the cost associated with repeated calls, whether it is the cost of managing multiple registrable domains or the user experience friction of opening multiple windows (tabs or pop-ups).
This section is non-normative.
For the user-facing aspects of Payment Request API, implementations integrate with platform accessibility APIs via form controls and other input modalities. Furthermore, to increase the intelligibility of total, shipping addresses, and contact information, implementations format data according to system conventions.
This specification relies on several other underlying specifications.
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, MUST NOT, OPTIONAL, RECOMMENDED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
There is only one class of product that can claim conformance to this specification: a user agent.
Although this specification is primarily targeted at web browsers, it is feasible that other software could also implement this specification in a conforming manner.
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.
User agents MAY impose implementation-specific limits on otherwise
unconstrained inputs, e.g., to prevent denial of service attacks, to
guard against running out of memory, or to work around
platform-specific limitations. When an input exceeds
implementation-specific limit, the user agent MUST throw, or, in the
context of a promise, reject with, a TypeError
optionally informing
the developer of how a particular input exceeded an
implementation-specific limit.
WebIDL[SecureContext, Exposed=Window]
interface PaymentRequest
: EventTarget {
constructor
(
sequence<PaymentMethodData
> methodData,
PaymentDetailsInit
details,
optional PaymentOptions
options = {}
);
[NewObject]
Promise<PaymentResponse
> show
(optional Promise<PaymentDetailsUpdate
> detailsPromise);
[NewObject]
Promise<undefined> abort
();
[NewObject]
Promise<boolean> canMakePayment
();
readonly attribute DOMString id
;
readonly attribute ContactAddress? shippingAddress
;
readonly attribute DOMString? shippingOption
;
readonly attribute PaymentShippingType
? shippingType
;
attribute EventHandler onshippingaddresschange
;
attribute EventHandler onshippingoptionchange
;
attribute EventHandler onpaymentmethodchange
;
};
dictionary PaymentMethodData
{
required DOMString supportedMethods
;
object data
;
};
dictionary PaymentCurrencyAmount
{
required DOMString currency
;
required DOMString value
;
};
dictionary PaymentDetailsBase
{
sequence<PaymentItem
> displayItems
;
sequence<PaymentShippingOption
> shippingOptions
;
sequence<PaymentDetailsModifier
> modifiers
;
};
dictionary PaymentDetailsInit
: PaymentDetailsBase
{
DOMString id
;
required PaymentItem
total
;
};
dictionary PaymentDetailsUpdate
: PaymentDetailsBase
{
DOMString error
;
PaymentItem
total
;
AddressErrors
shippingAddressErrors
;
PayerErrors
payerErrors
;
object paymentMethodErrors
;
};
dictionary PaymentDetailsModifier
{
required DOMString supportedMethods
;
PaymentItem
total
;
sequence<PaymentItem
> additionalDisplayItems
;
object data
;
};
enum PaymentShippingType
{
"shipping
",
"delivery
",
"pickup
"
};
dictionary PaymentOptions
{
boolean requestPayerName
= false;
boolean requestBillingAddress
= false;
boolean requestPayerEmail
= false;
boolean requestPayerPhone
= false;
boolean requestShipping
= false;
PaymentShippingType
shippingType
= "shipping";
};
dictionary PaymentItem
{
required DOMString label
;
required PaymentCurrencyAmount
amount
;
boolean pending
= false;
};
dictionary PaymentCompleteDetails
{
object? data
= null;
};
enum PaymentComplete
{
"fail
",
"success
",
"unknown
"
};
dictionary PaymentShippingOption
{
required DOMString id
;
required DOMString label
;
required PaymentCurrencyAmount
amount
;
boolean selected
= false;
};
[SecureContext, Exposed=Window]
interface PaymentResponse
: EventTarget {
[Default] object toJSON();
readonly attribute DOMString requestId
;
readonly attribute DOMString methodName
;
readonly attribute object details
;
readonly attribute ContactAddress? shippingAddress
;
readonly attribute DOMString? shippingOption
;
readonly attribute DOMString? payerName
;
readonly attribute DOMString? payerEmail
;
readonly attribute DOMString? payerPhone
;
[NewObject]
Promise<undefined> complete
(
optional PaymentComplete
result = "unknown",
optional PaymentCompleteDetails
details = {}
);
[NewObject]
Promise<undefined> retry
(optional PaymentValidationErrors
errorFields = {});
attribute EventHandler onpayerdetailchange
;
};
dictionary PaymentValidationErrors
{
PayerErrors
payer
;
AddressErrors
shippingAddress
;
DOMString error
;
object paymentMethod
;
};
dictionary PayerErrors
{
DOMString email
;
DOMString name
;
DOMString phone
;
};
dictionary AddressErrors
{
DOMString addressLine
;
DOMString city
;
DOMString country
;
DOMString dependentLocality
;
DOMString organization
;
DOMString phone
;
DOMString postalCode
;
DOMString recipient
;
DOMString region
;
DOMString sortingCode
;
};
[SecureContext, Exposed=Window]
interface PaymentMethodChangeEvent
: PaymentRequestUpdateEvent
{
constructor
(DOMString type, optional PaymentMethodChangeEventInit
eventInitDict = {});
readonly attribute DOMString methodName
;
readonly attribute object? methodDetails
;
};
dictionary PaymentMethodChangeEventInit
: PaymentRequestUpdateEventInit
{
DOMString methodName
= "";
object? methodDetails
= null;
};
[SecureContext, Exposed=Window]
interface PaymentRequestUpdateEvent
: Event {
constructor
(DOMString type, optional PaymentRequestUpdateEventInit
eventInitDict = {});
undefined updateWith
(Promise<PaymentDetailsUpdate
> detailsPromise);
};
dictionary PaymentRequestUpdateEventInit
: EventInit {};
This specification was derived from a report published previously by the Web Platform Incubator Community Group.
Changes from between CR2 until now:
Changes from between CR1 and CR2:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: