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.
Status of This Document
This is a
preview
Do not attempt to implement this version of the specification. Do not
reference this version as authoritative in any way.
Instead, see
https://w3c.github.io/payment-request/ for the Editor's draft.
This section describes the status of this
document at the time of its publication. Other documents may supersede
this document. A list of current W3C publications and the latest revision
of this technical report can be found in the
W3C technical reports index at
https://www.w3.org/TR/.
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.
Publication as an Editor's Draft does not imply endorsement by the W3C
Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress.
This document was produced by a group
operating under the
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.
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).
Defined handling of multiple applicable modifiers.
1.
Introduction
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:
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.
1.1
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.
2.1
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.
Here we see how to add a processing fee for using a card on a
particular network. Notice that it requires recalculating the total.
Example 4: Modifying payment request based on card type
// Certain cards incur 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 });
2.5
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.
asyncfunctiondoPaymentRequest() {
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, SecurityErrorconsole.error(err);
}
}
asyncfunctionvalidateResponse(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();
2.7
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.
request.onshippingaddresschange = ev => {
ev.updateWith(validateAddress(request.shippingAddress));
};
functionvalidateAddress(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 };
}
2.9
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 Standard:
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.
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.
For auditing and reconciliation purposes, a merchant can associate
a unique identifier for each transaction with the
id attribute.
3.3
show() method
Note
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:
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 user's
preference when presenting payment methods.
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.
A true result from canMakePayment() does not imply that the
user has a provisioned instrument ready for payment. For that, use
hasEnrolledInstrument() instead.
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.
Note
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).
Note: Digital currencies and ISO 4217 currency codes
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).
Note
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 agentMAY display.
Note
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 indicates whether the user agentSHOULD collect
and return 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. 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
A boolean that indicates whether the user agentSHOULD 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 agentSHOULD 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 agentSHOULD 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 agentSHOULD 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 agentsMAY indicate pending fields in
the user interface for the payment request.
11.
Physical addresses
A physical address is composed of the following parts.
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.
City
The city/town portion of the address.
Country
The country corresponding to the address.
Dependent locality
The dependent locality or sublocality within a city. For example,
neighborhoods, boroughs, districts, or UK dependent localities.
Organization
The organization, firm, company, or institution at the address.
Phone number
The phone number of the recipient or contact person at the address.
Postal code
The postal code or ZIP code, also known as PIN code in India.
Recipient
The name of the recipient or contact person at the address.
Region
The top level administrative subdivision of the country. For example,
this can be a state, a province, an oblast, or a prefecture.
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).
Note
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.
11.4
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.
Note: Privacy of recipient information (the redactList)
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 a newly created AddressInit dictionary.
If "addressLine" is not in redactList, set
details["addressLine"] to the result of splitting the
user-provided address line into a list.
Note
If "country" is not in redactList, set
details["country"] to the user-provided country as an upper
case [ISO3166-1] alpha-2 code.
If "phone" is not in redactList, set details["phone"]
to the user-provided phone number.
Note: Privacy of phone number
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.
If "organization" is not in redactList, set
details["organization"] to the user-provided recipient
organization.
If "postalCode" is not in redactList, set
details["postalCode"] to the user-provided postal code.
Optionally, redact part of details["postalCode"].
Note: Privacy of Postal Codes
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.
If "region" is not in redactList:
Note: Countries where regions are not commonly used
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.
If "sortingCode" is not in redactList, set
details["sortingCode"] to the user-provided sorting code.
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 agentsSHOULD
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.
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.
The corresponding payment request id that spawned
this payment response.
14.11
complete() method
Note
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'.
Note
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 can make payment algorithm checks if the user
agent supports making payment with the payment methods
with which the PaymentRequest was constructed. It takes a boolean
argument, checkForInstruments, that specifies whether the algorithm
checks for existence of enrolled instruments in addition to
supporting a payment method.
Let request be the PaymentRequest object on
which the method was called.
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.
Let identifier be the first element in the paymentMethod
tuple.
If checkForInstruments is false, and the user agent has a
payment handler that supports handling payment requests
for identifier, resolve hasHandlerPromise with true and
terminate this algorithm.
If checkForInstruments is true:
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. Otherwise, convert to object.
Let handlers be a list of registered payment
handlers that are authorized and can handle payment
request for identifier.
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.
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.
The user accepts the
payment request algorithm runs when the user accepts the
payment request and confirms that they want to pay. It MUSTqueue
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 agentSHOULD 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 MUSTqueue 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.
18.10
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.
19.
Privacy and Security Considerations
19.1
User protections with show() method
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().
19.2
Secure contexts
This section is non-normative.
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.
19.3
Cross-origin payment requests
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 HTMLIFrameElement.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.
19.5
How user agents match payment handlers
This section is non-normative.
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.
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.
19.7
Exposing user information
The user agentMUST NOT share information about the user with
a developer (e.g., the shipping address) without user consent.
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:
Support for instructions from the payee identifying specific
elements to exclude or include from the payment method
response data (returned through 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() and hasEnrolledInstrument()
methods have the potential to expose user information that could be
abused for fingerprinting purposes. 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).
20.
Accessibility Considerations
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.
21.
Dependencies
This specification relies on several other underlying specifications.
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.
ISO 3366-2
Country subdivision
name and country subdivision code element are
defined in [ISO3166-2].
22. Conformance
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.
Note
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.
