Copyright © 2018 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
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.
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 maintains a list of all bug reports that the group has not yet addressed. Pull requests with proposed specification text for outstanding issues are strongly encouraged.
If you wish to make comments regarding this document, please raise them as GitHub issues. Only send comments by email if you are unable to raise issues on GitHub (see links below). All comments are welcome.
This document was published by the Web Payments Working Group as a Working Draft.
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 document is governed by the 1 February 2018 W3C Process Document.
This section is non-normative.
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 [HTML] 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.
The standardized
payment method identifier for this specification is
"basic-card
".
This section defines concepts used in this specification, and how those concepts are represented in an API via [WEBIDL].
A card is a physical or virtual payment instrument that has details, a type, and belongs to a network.
The details of a card are the primary account number (PAN), 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.
A card can be of type "credit",
"debit", or "prepaid", as derived from the issuer identification number
(the first eight digits of the primary account number). The
different types are represented as the BasicCardType
enum.
A card is identified as belonging to a network via its issuer identification number [ISO7812-1] (e.g., those belonging to "visa" start with a "4"). In an API, each network is represented by a string matching one of the card network identifiers [card-network-ids].
A payment handler's known networks are networks it supports. A payment handler MAY support zero or more networks from the [card-network-ids] list.
BasicCardRequest
dictionary
dictionary BasicCardRequest
{
sequence<DOMString> supportedNetworks
;
sequence<BasicCardType
> supportedTypes
;
};
The BasicCardRequest
dictionary contains the following members:
supportedNetworks
supportedTypes
The steps to constrain a payment handler with
BasicCardRequest
data are given by the following
algorithm. If the end user inputs or selects a card that meets
the constraints of data, the algorithm returns a card as a
BasicCardResponse
.
supportedNetworks
"]
for networks that are known by this payment handler.
supportedTypes
"].
BasicCardResponse
.
cardNumber
"] to a string of digits of
length between 10 to 19 items representing the primary account
number. The primary account number SHOULD be one of the
types from requestedTypes, or any type if
requestedTypes is empty.
cardNumber
"] is from one of the
networks in requestedNetworks, or any network
if requestedNetworks is empty. Optionally, validate
card's details to make sure they adhere to any
type and/or network requirements.
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 for the expected type, 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.
cardholderName
"] to the card
holder's name, or the empty string if the user chooses not to
provide it.
cardSecurityCode
"] to a three or more
digit string, or the empty string if the user chooses not to provide
it.
expiryMonth
"] to two-digit string
ranging from "01
" to "12
", or the empty
string if the user chooses not to provide it or the type doesn't
require an expiry month.
expiryYear
"] to a four-digit string in
the range "0000
" to "9999
", or the empty
string if the user chooses not to provide it or the type doesn't
require an expiry year.
billingAddress
"] to the
result running the steps to create a payment
address. Alternatively, if a billing address is not required for
this card type, then set
card["billingAddress
"] to null.
BasicCardType
enum
enum BasicCardType
{
"credit",
"debit",
"prepaid"
};
credit
"
debit
"
prepaid
"
BasicCardResponse
dictionary
dictionary BasicCardResponse
{
required DOMString cardNumber
;
DOMString cardholderName
;
DOMString cardSecurityCode
;
DOMString expiryMonth
;
DOMString expiryYear
;
PaymentAddress
? billingAddress
;
};
cardholderName
member
cardNumber
member
expiryMonth
member
01
" to "12
".
expiryYear
member
0000
" to "9999
".
cardSecurityCode
member
billingAddress
member
PaymentAddress
that represents the billing address associated with the
card, or null.
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, SHOULD, and SHOULD 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.
A conforming payment handler MUST:
basic-card
" standardized
payment method identifier.
BasicCardResponse
s whose members are formatted as per
their definition in this specification.
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.
Owners of web sites SHOULD NOT store the payer's card information except where warranted, such as storage for future and recurring payments. When card information is stored, web site owners SHOULD take measures to prevent its disclosure.
Depending on jurisdiction, users of this specification (implementers, merchants, payment processors, etc.) can be subject to PCI DSS or other regulations. Discussion of those considerations are outside the scope of this document.