This specification describes data structures and formats, and a simple
processing model, to facilitate card-based payments on the Web. It is
used by other specifications to facilitate monetary transactions with a
"basic-card", such as credit, debit, or prepaid card.
Status of This Document
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/.
GitHub Issues are preferred for
discussion of this specification.
Publication as a Working Draft does not imply endorsement by the
W3C Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress.
This document was produced by a group
operating under the
W3C Patent Policy.
The group does not expect this document to become a W3C Recommendation.
W3C maintains a
public list of any patent disclosures
made in connection with the deliverables of
the group; that page also includes
instructions for disclosing a patent. An individual who has actual
knowledge of a patent which the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy.
This specification defines the "basic-card" payment method for use, for
instance, with the Payment Request API. With it, merchants can
request the card details (card holder name, card number, etc.)
from the end user as an alternative to collecting the same information
through a form.
The basic card payment method provides information to merchant websites
that can be used for multiple transactions over a potentially very long
period of time, typically on the order of several years at a time. At
the time of the development of this specification, it is commonplace
for merchant sites to store this information long-term to reduce the
friction of a user entering a credit card number for every future
purchase.
The decision whether to retain credit card information for future
transactions remains a matter of local policy for web sites; however,
the introduction of a programmatic way to retrieve credit card
information from a web browser affects some key factors that typically
motivate storage of such information.
Because the web browser will retain credit card information, and make
it available – subject to user approval – whenever a merchant needs it,
the friction that merchants seek to avoid is reduced. This can also
potentially reduce some liability considerations of storing information
on a persistent basis, such as financial liability that can result from
unauthorized access to the databases used to store credit card
information.
Additionally, web sites that call the Payment Request API for each
transaction avoid the friction that can result when users’ credit card
numbers and/or expiration dates are updated. From a user’s perspective,
this avoids the hassle of having to update a large number of merchant
web sites any time they are issued a new card.
Finally, by letting the web browser determine user authentication
information, the merchant site is relieved of the duty of ensuring that
a time-local and sufficiently strong authentication has occurred.
Additionally, payment handlers can make use of local affordances, such
as biometrics and hardware tokens, to authenticate users in a way that
is more convenient, more secure, and lower friction than web sites
currently can.
A card is a physical or virtual payment
instrument that has details and optionally is part of a
network.
The details of a card are the primary account number (PAN) [ISO7812-1], card holder's
name, security code (sometimes known as the CVV, CVC,
CVN, CVE or CID), expiry month, expiry year, and
optionally a billing address. These are represented as the
members of the BasicCardResponse dictionary.
The steps to check if an instrument is supported take as
input a cardcard and a list of networknetworks. It returns true if the card is supported, false
otherwise.
If networks includes the card's network, return
true. Otherwise, return false.
5.3
Steps to respond to a payment request
The steps to respond to a payment request are given by the
following algorithm. The steps take PaymentRequestrequest as input. If the end user inputs or selects
a card that meets the constraints of BasicCardRequestdata the algorithm returns a card as a
BasicCardResponse.
Set card.cardNumber to a user provided, or otherwise
generated, string of digits of length between 10 to 19 items
representing the primary account number.
If the card supports a security code and the user
chooses provide it, set card.cardSecurityCode to a three or
more digit string.
If the card supports an expiry month and the user
chooses to provide it, set card.expiryMonth to two-digit
string ranging from "01" to "12".
If the card supports an expiry year and the user
chooses provide it, set card.expiryYear to a four-digit
string in the range "0000" to "9999".
If request.[[options]]["requestBillingAddress"]
is true, or, optionally, the user agent determines that payment is
taking place in region where validation of billing addresses against
an address verification system is the norm:
Let redactList be at least « "addressLine",
"organization", "phone", "recipient" ».
Optionally, validate card's details to make sure they
adhere to any additional network requirements and assist
the user in fixing any issues encountered.
Note: Validation of inputs
The validation a user agent performs on the card's
details is a quality of implementation detail and
outside the scope of this specification. There is nevertheless
an expectation that user agents will make a best effort to
check that a card number is valid as per the Luhn algorithm
[ISO7812-1], check the length is correct , check that the
issuer identification number is correct for the selected
network, check that the expiry date on the card hasn't
lapsed, and so on.
Return card.
5.4
Steps for when a user changes payment method
Note
When the end user explicitly switches from one card to another, these
steps cause an event to fire in the Payment Request API. The
algorithm presupposes that the user agent is only presenting
supported cards to the end user, by having filtered out
unsupported cards based on the initiating payment request's
BasicCardRequest's supportedNetworks values.
The steps for when a user changes payment method are as
follows. The steps take PaymentRequestrequest as input. To
mitigate fingerprinting concerns, the user agent MUST NOT run these
steps unless a user explicitly switches to a different card by
performing some user action (e.g., by selecting a different card
explicitly from a list of cards). For cards that are preselected by
default by the user agent, any matching PaymentDetailsModifiers
apply instead (without the need
to run these steps).
Let redactList be at least « "addressLine",
"organization", "phone", "recipient" ».
Note: Privacy of recipient information
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 tax,
but, in most cases, not enough information to physically
locate and uniquely identify the payer.
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.
Optionally, redact billingAddress.postalCode
to make it more privacy preserving, but providing enough detail
so that, for example, it can still be used to calculate tax.
If the merchant requested the billing address, a redacted
PaymentAddress that represents the billing address
associated with the card. If the merchant does not request
the billing address, it's null.
5.5
Selecting the payment handler
Note
In the case where a payment request is made with multiple
applicable PaymentMethodDatas, this algorithm selects the
last applicable [[serializedMethodData]]
whose PMI is "basic-card". (i.e., "the last one
wins").
const methodData = [
// This one matches, but is ignored since one the follows also matches.
{
supportedMethods: "basic-card",
data: {
supportedNetworks: ["visa", "mastercard"],
},
},
// ✅ This second one gets used!
{
supportedMethods: "basic-card",
data: {
supportedNetworks: ["visa"],
},
},
// This one gets skipped, because it's not applicable to// basic card.
{
supportedMethods: "https://example.com/bobpay",
},
];
// See above for which methodData gets picked.awaitnew PaymentRequest(methodData, details, options).show();
The steps for selecting the payment handler are given by
the following algorithm. These steps run when a payment UI is first
presented to the end-user, as a successful call to a
PaymentRequest's show()
method. The steps take a PaymentRequestrequest.
Apply restrictions's supportedNetworks member to
constrain the card type inputs of the payment UI. When the sequence
is empty, it means that all networks are supported.
If a payment instrument is selected by default, apply the
modifiers using request and passing the identifier for
network of the selected instrument.
5.6
Applying the modifiers
The steps to apply the modifiers are given by the
following algorithm. It takes a PaymentRequestrequest and a string networkIdentifier that
identifies a network:
As well as sections marked as non-normative, all authoring guidelines,
diagrams, examples, and notes in this specification are non-normative.
Everything else in this specification is normative.
The key words MAY, MUST, and MUST NOT
are to be interpreted as described in
[RFC2119].
There is only one class of product that can claim conformance to this
specification: a payment handler.
return
BasicCardResponses whose members are formatted per their
definition in this specification.
10.
Security and Privacy Considerations
This section is non-normative.
Due to differences in quality of implementation and the end user's
ability to input data into unconstrained input fields, merchants are
expected to revalidate all BasicCardResponse returned by APIs
that make use of this specification.
In particular, merchants need to treat the values of any details
with the same scrutiny that they would apply to a [HTML]
input element, by, for example, sanitizing all the members
of a BasicCardResponse before rendering them anywhere.
Depending on jurisdiction, users of this specification (implementers,
merchants, payment processors, etc.) can be subject to Payment Card Industry Data Security Standard Compliance (PCI DSS)
or other regulations. Discussion of those considerations are outside
the scope of this document.