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.
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).
There has been no change in dependencies on other workings groups
during the development of this specification.
Changes since last publication
Substantive changes to the Payment Request API since the 9 July 2018
version are as follows. The complete list of changes, including all
editorial changes, is viewable in the commit
history.
Added support for notification when the user selects a payment
handler, but before confirming payment. This allows merchant to
update totals, validate acceptance, etc.
Added support to notify site of billing address selection. This
allows a merchant to update a total (e.g., for VAT in Europe). To
enhance privacy, only some billing address data is returned to the
merchant as long as the user has not confirmed payment.
Added support for retry() and fine-grain error reporting
to the user.
Added support for merchant validation by the payment handler.
Clearer definition of
canMakePayment() and worked to align implementations.
canMakePayment() does not reveal whether payment handler is
primed to pay.
Removed languageCode and regionCode
from PaymentAddress.
Removed currencySystem.
"Payment request is showing" boolean now attached to
top-level browsing context. Previously, only a single payment UI was
allowed to be shown at a time across the whole browser. This now
allows multiple browser tabs to show a payment UI at the same time
(for those payment handlers able to support it).
Integrated with .
Defined handling of multiple applicable modifiers.
Introduction
This specification describes an API that allows user agents
(e.g., browsers) to act as an intermediary between three parties in a
transaction:
The payee: the merchant that runs an online store, or other party
that requests to be paid.
The payer: the party that makes a purchase at that online store,
and who authenticates and authorizes payment as required.
The payment method: the means that the payer uses to pay
the payee (e.g., a basic card payment). The payment method
provider establishes the ecosystem to support that payment
method.
The details of how to fulfill a payment request for a given payment
method is an implementation detail of a payment handler.
Concretely, each payment handler defines:
Steps to check if a payment can be made:
How a payment handler determines whether it, or the user, can
potentially "make a payment" is also an implementation detail of a
payment handler. For an example, see the can
make payment algorithm of [[?payment-method-basic-card]].
Steps to respond to a payment request:
Steps that return an object or dictionary that a merchant uses to
process or validate the transaction. The structure of this object is
specific to each payment method. For an example of such an
object, see the BasicCardResponse
dictionary of [[?payment-method-basic-card]].
Steps for when a user changes payment method (optional)
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.
Goals and scope
Allow the user agent to act as intermediary between a merchant,
user, and payment method provider.
Enable user agents to streamline the user's payment experience by
taking into account user preferences, merchant information, security
considerations, and other factors.
Standardize (to the extent that it makes sense) the communication
flow between a merchant, user agent, and payment method
provider.
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:
The methodData: A sequence of PaymentMethodDatas
that represents the payment methods that the site supports
(e.g., "we support card-based payments, but only Visa and MasterCard
credit cards.").
The details: The details of the transaction, as a
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".
The options: Optionally, a list of things as
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.
Declaring multiple ways of paying
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).
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: "USD", value: "55.00" },
},
{
label: "Sales Tax",
amount: { currency: "USD", value: "5.00" },
type: "tax"
},
],
total: {
label: "Total due",
// The total is USD$65.00 here because we need to
// add shipping (below). The selected shipping
// costs USD$5.00.
amount: { currency: "USD", value: "65.00" },
},
};
Adding shipping options
Here we see an example of how to add two shipping options to the
details.
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 incurs a $3.00 processing fee.
const cardFee = {
label: "Card processing fee",
amount: { currency: "USD", value: "3.00" },
};
// Modifiers apply when the user chooses to pay with
// a card.
const modifiers = [
{
additionalDisplayItems: [cardFee],
supportedMethods: "basic-card",
total: {
label: "Total due",
amount: { currency: "USD", value: "68.00" },
},
data: {
supportedNetworks: networks,
},
},
];
Object.assign(details, { modifiers });
Requesting specific information from the end user
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.
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 request.retry(errors);
return validateResponse(response);
}
await response.complete("success");
} catch (err) {
// Something went wrong...
await response.complete("fail");
}
}
doPaymentRequest();
Handling events and updating the payment request
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 json = request.shippingAddress.toJSON();
await ensureCanShipTo(json);
const { shippingOptions, total } = await calculateShipping(json);
return { shippingOptions, total };
} catch (err) {
return { error: `Sorry! we can't ship to your address.` };
}
}
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 };
}
POSTing payment response back to a server
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 provides a toJSON() method that
serializes the object directly into JSON. This makes it trivial to
POST the resulting JSON back to a server using the Fetch API:
async function doPaymentRequest() {
const payRequest = new PaymentRequest(methodData, details, options);
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();
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 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.
If
details.id is
missing, add an id
member to details and set its value to a
UUID
[[RFC4122]].
Let serializedMethodData be an empty list.
Process payment methods:
If the length of the methodData sequence is zero,
then throw a TypeError, optionally informing the
developer that at least one payment method is required.
If the data
member of paymentMethod is missing, let
serializedData be null. Otherwise, let
serializedData be the result of
JSON-serializingpaymentMethod.data
into a string. Rethrow any exceptions.
If serializedData is not null, and if required
by the specification that defines the
paymentMethod.supportedMethods:
Let object be the result of
JSON-parsingserializedData.
Convertobject
to an IDL value of the type specified by the
specification that defines the
paymentMethod.supportedMethods
(e.g., a BasicCardRequest
in the case of [[?payment-method-basic-card]]).
Rethrow any exceptions.
This step assures that any IDL type conversion errors
are caught as early as possible.
Add the tuple (paymentMethod.supportedMethods,
serializedData) to
serializedMethodData.
If the data member of
modifier is missing, let
serializedData be null. Otherwise, let
serializedData be the result of
JSON-serializingmodifier.data into a string.
Rethrow any exceptions.
Add the tuple (modifier.supportedMethods,
serializedData) to
serializedModifierData.
Remove the
data member of modifier, if it is
present.
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:
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 .
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.
Let identifier be the first element in the
paymentMethod tuple.
Let data be the result of JSON-parsing the second element
in the paymentMethod tuple.
If required by the specification that defines the
identifier, then convertdata to an IDL value of the type specified there.
Otherwise, convert to
object.
Present a user interface that will allow the user to interact
with the handlers. The user agent SHOULD prioritize the
preference of the user when presenting payment methods. It is
RECOMMENDED that the language of the user interface match the
language of the body element.
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 fulfillmentdetailsPromise, the user agent re-enables the
payment request UI and the payment flow can continue.
Let handler be the payment handler selected by
the end-user.
If the first element of tuple (a PMI)
matches the payment method identifier of
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 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.
Let identifier be the first element in the
paymentMethod tuple.
If the user agent has a payment handler that supports
handling payment requests for identifier, resolve
hasHandlerPromise with true and terminate this
algorithm.
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.
An object that provides optional information that might be needed by
the supported payment methods. If supplied, it will be
JSON-serialized.
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.
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. Where a localized currency symbol is not
available, a user agent SHOULD use U+00A4 (¤) for formatting. 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 "$", "GBP"
is "£", and the non-standard "XBT" could be shown as "Ƀ"). When a
code cannot be matched, the specification recommends browsers
show a scarab "¤".
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.
A JavaScript string is
a valid decimal monetary value if it consists of the
following code points in the given order:
Optionally, a single U+002D (-), to indicate that the amount is
negative.
One or more code points in the range U+0030 (0) to U+0039
(9).
Optionally, a single U+002E (.) followed by one or more code
points in the range U+0030 (0) to U+0039 (9).
The following regular expression is an implementation of the above
definition.
^-?[0-9]+(\.[0-9]+)?$
To check and canonicalize amount given a
PaymentCurrencyAmountamount, run the following
steps:
If the result of IsWellFormedCurrencyCode(amount.currency)
is false, then throw a RangeError exception, optionally
informing the developer that the currency is invalid.
If the first code point of amount.value
is U+002D (-), then throw a TypeError optionally informing the
developer that a total's value can't be a negative number.
A sequence of 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.
A sequence of PaymentDetailsModifier dictionaries that
contains modifiers for particular payment method identifiers. For
example, it allows you to adjust the total amount based on payment
method.
A human-readable string that explains why goods cannot be shipped
to the chosen shipping address, or any other reason why no shipping
options are available. When the payment request is updated using
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).
A sequence of 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.
This is the default and refers to the address being collected as the
destination for shipping.
"delivery"
This refers to the address being collected as the destination for
delivery. This is commonly faster than shipping. For example, it
might be used for food delivery.
"pickup"
This refers to the address being collected as part of a service
pickup. For example, this could be the address for laundry pickup.
The PaymentOptions dictionary is passed to the
PaymentRequest constructor and provides information about the
options desired for the payment request.
requestBillingAddress member
A boolean that instructs the user agent to get the billing
address associated with a payment method (e.g., the billing
address associated with a credit card). Typically, the user agent
will return the billing address as part of the
PaymentMethodChangeEvent's methodDetails, albeit
possibly with parts of the address redacted for privacy reasons. A
merchant can use this information to, for example, calculate tax in
certain jurisdictions.
requestPayerName member
A boolean that indicates whether the user agent SHOULD collect
and return the payer's name as part of the payment request. For
example, this would be set to true to allow a merchant to make a
booking in the payer's name.
requestPayerEmail member
A boolean that indicates whether the user agent SHOULD collect
and return the payer's email address as part of the payment request.
For example, this would be set to true to allow a merchant to email a
receipt.
requestPayerPhone member
A boolean that indicates whether the user agent SHOULD collect
and return the payer's phone number as part of the payment request.
For example, this would be set to true to allow a merchant to phone a
customer with a billing enquiry.
requestShipping member
A boolean that indicates whether the user agent SHOULD collect
and return a shipping address as part of the payment request. For
example, this would be set to true when physical goods need to be
shipped by the merchant to the user. This would be set to false for
the purchase of digital goods.
shippingType member
A 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.
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
A human-readable description of the item. The user agent may
display this to the user.
A boolean. When set to true it means that the 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.
Physical addresses
A physical address is composed of the following parts.
Country
The country corresponding to the address.
Address line
The most specific part of the address. It can include, for example, a
street name, a house number, apartment number, a rural delivery
route, descriptive instructions, or a post office box number.
Region
The top level administrative subdivision of the country. For example,
this can be a state, a province, an oblast, or a prefecture.
City
The city/town portion of the address.
Dependent locality
The dependent locality or sublocality within a city. For example,
neighborhoods, boroughs, districts, or UK dependent localities.
Postal code
The postal code or ZIP code, also known as PIN code in India.
Sorting code
The sorting code as used in, for example, France.
Organization
The organization, firm, company, or institution at the address.
Recipient
The name of the recipient or contact person at the address.
Phone number
The phone number of the recipient or contact person at the address.
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
Denotes that the address line has a validation error. In the
user agent's UI, this member corresponds to the input field that
provided the PaymentAddress's addressLine attribute's value.
city member
Denotes that the city has a validation error. In the user
agent's UI, this member corresponds to the input field that
provided the PaymentAddress's city attribute's value.
country member
Denotes that the country has a validation error. In the user
agent's UI, this member corresponds to the input field that
provided the PaymentAddress's country attribute's value.
dependentLocality member
Denotes that the dependent locality has a validation error.
In the user agent's UI, this member corresponds to the input field
that provided the PaymentAddress's dependentLocality attribute's value.
organization member
Denotes that the organization has a validation error. In the
user agent's UI, this member corresponds to the input field that
provided the PaymentAddress's organization attribute's value.
phone member
Denotes that the phone number has a validation error. In the
user agent's UI, this member corresponds to the input field that
provided the PaymentAddress's phone attribute's value.
postalCode member
Denotes that the postal code has a validation error. In the
user agent's UI, this member corresponds to the input field that
provided the PaymentAddress's postalCode attribute's value.
recipient member
Denotes that the recipient has a validation error. In the
user agent's UI, this member corresponds to the input field that
provided the PaymentAddress's addressLine attribute's value.
region member
Denotes that the region has a validation error. In the user
agent's UI, this member corresponds to the input field that
provided the PaymentAddress's region attribute's value.
sortingCode member
The sorting code has a validation error. In the user agent's
UI, this member corresponds to the input field that provided the
PaymentAddress's sortingCode attribute's value.
Creating a PaymentAddress from user-provided input
The steps to create a PaymentAddress from
user-provided input are given by the following algorithm. The
algorithm takes a listredactList.
The redactList optionally gives user agents the
possibility to limit the amount of personal information about the
recipient that the API shares with the merchant.
For merchants, the resulting PaymentAddress 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.
Let details be an AddressInit dictionary with
no members present.
If "addressLine" is not in redactList, set
details["addressLine"] to the result of splitting
the user-provided address line into a list. If none was
provided, set it to the empty list.
If "country" is not in redactList, set
details["country"] to the user-provided country as
an upper case [[ISO3166-1]] alpha-2 code, or to the empty string if
none was provided.
If "phone" is not in redactList, set
details["phone"] to the user-provided phone number,
or to the empty string if none was provided.
If "city" is not in redactList, set
details["city"] to the user-provided city, or to
the empty string if none was provided.
If "dependentLocality" is not in redactList, set
details["dependentLocality"] to the user-provided
dependent locality, or to the empty string if none was provided.
If "organization" is not in redactList, set
details["organization"] to the user-provided
recipient organization, or to the empty string if none was provided.
If "postalCode" is not in redactList, set
details["postalCode"] to the user-provided postal
code, or to the empty string if none was provided. Optionally, redact
part of details["postalCode"].
Postal codes in certain countries can be so specific as
to uniquely identify an individual. This being a privacy
concern, some user agents only return the part of a postal code
that they deem sufficient for a merchant to calculate shipping
costs. This varies across countries and regions, and so the
choice to redact part, or all, of the postal code is left to
the discretion of implementers in the interest of protecting
users' privacy.
If "recipient" is not in redactList, set
details["recipient"] to the user-provided recipient
of the transaction, or to the empty string if none was provided.
If "region" is not in redactList:
In some countries (e.g., Belgium) it is uncommon for users to
include a region as part of a physical address
(even if all the regions of a country are part of [[ISO3166-2]]).
As such, when the user agent knows that the user is inputting the
address for a particular country, it might not provide a field
for the user to input a region. In such cases, the user
agent returns an empty string for both PaymentAddress's
region attribute - but the
address can still serve its intended purpose (e.g., be valid for
shipping or billing purposes).
Set details["region"] to the user-provided
region, or to the empty string if none was provided.
If "sortingCode" is not in redactList, set
details["sortingCode"] to the user-provided sorting
code, or to the empty string if none was provided.
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.
A boolean. When true, it indicates that this is the default selected
PaymentShippingOption in a sequence. User agents SHOULD
display this option by default in the user interface.
If errorFields["paymentMethod] member was
passed, and if required by the specification that defines
response's payment method, then converterrorFields's paymentMethod member to an IDL
value of the type specified there. Otherwise, convert to
object.
By matching the
members of errorFields to input fields in the user
agent's UI, indicate to the end user that something is wrong with
the data of the payment response. For example, a user agent might
draw the user's attention to the erroneous errorFields
in the browser's UI and display the value of each field in a
manner that helps the user fix each error. Similarly, if the
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.
Otherwise, if errorFields was not passed, signal to
the end user to attempt to retry the payment. Re-enable any UI
element that affords the end user the ability to retry accepting the
payment request.
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:
A general description of an error with the payment from which the
user can attempt to recover. For example, the user may recover by
retrying the payment. A developer can optionally pass the
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
A payment method specific errors. See, for example,
[[?payment-method-basic-card]]'s BasicCardErrors.
Payer details are any of the payer's name, payer's phone
number, and payer's email.
email member
Denotes that the payer's email suffers from a validation error.
In the user agent's UI, this member corresponds to the input
field that provided the PaymentResponse's
payerEmail attribute's value.
name member
Denotes that the payer's name suffers from a validation error. In
the user agent's UI, this member corresponds to the input field
that provided the PaymentResponse's payerName
attribute's value.
phone member
Denotes that the payer's phone number suffers from a validation
error. In the user agent's UI, this member corresponds to the
input field that provided the PaymentResponse's
payerPhone attribute's value.
const payer = {
email: "The domain is invalid.",
phone: "Unknown country code.",
name: "Not in database.",
};
await response.retry({ payer });
The corresponding payment request id that spawned this payment response.
complete() method
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.
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.
This specification defines a policy-controlled feature identified by
the string "payment". Its default allowlist is
'self'.
A document’s feature
policy determines whether any content in that document is allowed
to construct PaymentRequest instances. If disabled in any
document, no content in the document will be allowed to use
the PaymentRequest constructor (trying to create an instance
will throw).
Initialize event.validationURL attribute to
validationURL.
If eventInitDict["methodName"] is not the
empty string, run the steps to validate
a payment method identifier with
eventInitDict["methodName"]. If it returns false,
then throw a RangeError exception. Optionally, inform the
developer that the payment method identifier is invalid.
A URL from which a developer can
fetch payment handler-specific verification data. By then
passing that data (or a promise that resolves with that data) to
complete(), the user agent can verify that the payment
request is from an authorized merchant.
When getting, returns the value it was initialized with.
Merchant validation is the
process by which a payment handler validates the identity of a
merchant against some value (usually some cryptographic
challenge response). Validated merchants are allowed to interface
with a payment handler. Details of how actual validation is
performed is outside the scope of this specification.
The redactList limits the amount of personal
information about the recipient that the API shares with
the merchant.
For merchants, the resulting PaymentAddress 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.
Let redactList be the empty list. Set
redactList to « "organization", "phone", "recipient",
"addressLine" ».
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:
Assert: request.[[\updating]] is false. Only
one update can take place at a time.
If
event.[[\waitForUpdate]] is true, disable any part
of the user interface that could cause another update event to be
fired.
Payer detail changed algorithm
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:
Let request be the PaymentRequest object that
the user is interacting with.
If
event.[[\waitForUpdate]] is true, disable any
part of the user interface that could cause another change to the
payer details to be fired.
User accepts the payment request algorithm
The user accepts the
payment request algorithm runs when the user accepts the
payment request and confirms that they want to pay. It MUST queue
a task on the user interaction task source to perform the
following steps:
Let request be the PaymentRequest object that
the user is interacting with.
If the request.[[\updating]] is true, then
terminate this algorithm and take no further action. The user
agent user interface SHOULD ensure that this never occurs.
If request.[[\state]] is not
"interactive", then terminate this algorithm and take no
further action. The user agent user interface SHOULD ensure
that this never occurs.
If the requestShipping value of
request.[[\options]] is true, then if the
shippingAddress
attribute of request is null or if the shippingOption attribute of
request is null, then terminate this algorithm and take no
further action. The user agent SHOULD ensure that this never
occurs.
Let isRetry be true if
request.[[\response]] is not null, false otherwise.
If the 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.
If the 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.
If the 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]].
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:
Let request be the PaymentRequest object that
the user is interacting with.
If request.[[\state]] is not
"interactive", then terminate this algorithm and take no
further action. The user agent user interface SHOULD ensure
that this never occurs.
Abort the current user interaction and close down any remaining
user interface.
Update a PaymentRequest's details algorithm
The update a PaymentRequest's details
algorithm takes a PaymentDetailsUpdatedetailsPromise, a PaymentRequestrequest, 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 parallel, disable the user interface that allows the user
to accept the payment request. This is to ensure that the payment
is not accepted until the user interface is updated with any new
details.
If the
data member of modifier is missing,
let serializedData be null. Otherwise,
let serializedData be the result of
JSON-serializingmodifier.data into a
string. If JSON-serializing throws an
exception, then abort the update with
request and that exception.
Add serializedData to
serializedModifierData.
Remove the data member of
modifier, if it is present.
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.
Likewise, if
details["paymentMethodErrors"] is
present, then display errors specifically for each
erroneous input field for the particular payment method.
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().
The validate merchant's details algorithm takes a
PromiseopaqueDataPromise and a
PaymentRequestrequest. The steps are conditional
on the opaqueDataPromise settling. If
opaqueDataPromise 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 opaqueDataPromise doesn't
settle in a reasonable amount of time. If an implementation chooses
to implement a timeout, they MUST execute the steps listed below in
the "upon rejection" path. Such a timeout is a fatal error for the
payment request.
In parallel, disable the user interface that allows the user
to accept the payment request. This is to ensure that the payment
is not accepted until the user interface is updated with any new
details.
Enable the user interface, allowing the request for payment
to proceed.
Privacy and Security Considerations
User protections with show() method
To help ensure that users do not inadvertently share sensitive
credentials with an origin, this API requires that PaymentRequest's
show() method be triggered by user 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().
Secure contexts
The API defined in this specification is only exposed in
secure contexts.
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.
Cross-origin payment requests
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 allowpaymentrequest attribute.
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.
How user agents match payment handlers
As part of show(), the user agent typically displays a list of
matching payment handlers that satisfy the payment
methods accepted by the merchant and other conditions. Matching
can take into account payment method information provided as
input to the API, information provided by the payment method
owner, the payment handlers registered by the user, user
preferences, and other considerations.
The user agent MUST NOT share information about the user with
a developer (e.g., the shipping address) without user consent.
One way that the API supports limited information sharing is through
the "redactList" associated with the creation of
physical addresses throughout the API. This feature enables
user agents to provide the payee with enough information to compute
shipping costs or tax information, while limiting the payee's ability
to identify the payer via the address.
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 enables the payee to determine —
before calling show() — whether the user agent knows of any
payment handlers available to the user that support the
payment methods provided to the PaymentRequestconstructor. If no
payment handlers support the payment methods, this
enables the payee to fall back to a legacy checkout experience.
Because this method shares some potentially unique information with
the payee, user agents are expected to protect the user from abuse of
the method. For example, user agents can reduce user fingerprinting
by:
These rate-limiting techniques intend to increase the cost associated
with repeated calls, whether it is the cost of managing multiple
eTLDs or the user experience friction of opening multiple windows
(tabs or pop-ups).
Accessibility Considerations
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.
Dependencies
This specification relies on several other underlying specifications.
ISO 3366-2
Country subdivision
name and country subdivision code element are
defined in [[ISO3166-2]].
Infra
The [[INFRA]] specification defines how to strip leading and
trailing ascii whitespace. It also defines the concept of a
list and code point.
Payment Method Identifiers
The term payment method identifier, or PMI
for short, is defined by [[payment-method-id]]. It's an unique
identifier for a payment method.
HTML
The following are defined by [[HTML]]: EventHandler,
queue a
task, user interaction
task source, top-level browsing
context, current settings
object, allowed to use,
triggered by
user activation, in parallel, the
iframe
element, and the allowpaymentrequest
attribute.
ECMAScript
The terms Promise, internal
slot, RangeError,
TypeError,
and JSON.stringify are
defined by [[ECMASCRIPT]].
The term JSON-serialize applied to
a given object means to run the algorithm specified by the original
value of the JSON.stringify function on the supplied object,
passing the supplied object as the sole argument, and return the
resulting string. This can throw an exception.
Writing Promise-Using Specifications
The terms a new
promise, a promise rejected
with, upon
fulfillment and upon rejection are defined by
[[PROMISES-GUIDE]].
DOM
The Event interface,
the EventTarget interface, the
EventInit
dictionary, and the terms fire an event, dispatch flag, stop propagation flag,
isTrusted
attribute, context object,
and stop
immediate propagation flag are defined by [[DOM]].
Web IDL
When this specification says to throw an error, the user agent must
throw an error as described in [[WEBIDL]]. When this occurs in a
sub-algorithm, this results in termination of execution of the
sub-algorithm and all ancestor algorithms until one is reached that
explicitly describes procedures for catching exceptions.
The algorithm for converting an ECMAScript value to a dictionary
is defined by [[WEBIDL]].
DOMException and the
following DOMException types from [[WEBIDL]] are used:
"AbortError",
"InvalidStateError",
"NotAllowedError",
"NotSupportedError", and
"SecurityError".
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.
