diff --git a/index.html b/index.html
index 3e9952e..2d1dbbf 100644
--- a/index.html
+++ b/index.html
@@ -40,7 +40,6 @@
],
doJsonLd: true,
github: "https://github.com/w3c/payment-method-basic-card/",
- highlightVars: true,
lint: { "check-punctuation": true },
noRecTrack: true,
previousMaturity: "FPWD",
@@ -50,6 +49,7 @@
wg: "Web Payments Working Group",
wgPatentURI: "https://www.w3.org/2004/01/pp-impl/83744/status",
wgURI: "https://www.w3.org/Payments/WG/",
+ xref: true,
};
@@ -73,10 +73,10 @@
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.
+ instance, with the . 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
@@ -105,11 +105,11 @@
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.
+ "payment-request"> 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
@@ -126,9 +126,10 @@
Payment Method Identifier
- The standardized
- payment method identifier for this specification is
+ payment method identifier (PMI ) for this specification is
"basic-card
".
@@ -142,19 +143,20 @@
- 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.
+ 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.
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 from the list of approved card network identifiers .
+ "card-network-ids">.
@@ -168,13 +170,12 @@
A supported card is a card
that when passed to the steps to check if an instrument is
- supported together with a list of networks returns true.
+ supported together with a list of |networks| returns true.
A payment handler's known networks are
networks it supports. A payment handler MAY support zero or more
- networks from the list of approved card
- network identifiers .
+ networks from the .
@@ -183,7 +184,7 @@
dictionary BasicCardRequest {
- sequence<DOMString> supportedNetworks;
+ sequence<DOMString> supportedNetworks = [];
};
@@ -195,8 +196,9 @@
A sequence of identifiers for card networks that the merchant
- accepts, derived from the list of
- approved card network identifiers .
+ accepts, derived from the . When
+ the sequence is empty, it means that all networks are
+ supported.
@@ -210,30 +212,29 @@
The steps to check if a payment can be made take a
- BasicCardRequest request as input. The steps return
- either true or false:
+ BasicCardRequest |request:BasicCardRequest| as input. The
+ steps return either true or false:
- Let cards be a list of
- cards associated with this payment handler.
+ Let |cards:list| be a list of cards associated with
+ this payment handler.
- If cards is
- empty , return false.
+ If |cards| is empty ,
+ return false.
- Let networks be an empty Let |networks:sequence| be an empty DOMString
sequence.
- If request ["supportedNetworks "] is present,
- append each item in request ["supportedNetworks "] to
- networks .
+ If |request|.supportedNetworks is present, append each
+ item in |request|.supportedNetworks to |networks|.
- For each card in cards :
+ For each |card| in |cards|:
- Let isSupported be the result of running the
+ Let |isSupported:boolean| be the result of running the
steps to check if an instrument is supported , passing in
- card and networks .
+ |card| and |networks|.
- If isSupported is true, then return true.
+ If |isSupported| is true, then return true.
@@ -247,16 +248,16 @@
The steps to check if an instrument is supported take as
- input a card card and a list of network networks . It
- returns true if the card is supported, false otherwise.
+ input a card |card:card| and a list of network
+ |networks:list|. It returns true if the |card| is supported, false
+ otherwise.
- If networks is
- empty , return true.
+ If |networks| is empty ,
+ return true.
- Return true if networks includes the card 's
- network , return true. Otherwise, return false.
+ If |networks| includes the card 's network , return
+ true. Otherwise, return false.
@@ -267,71 +268,69 @@
The steps to respond to a payment request are given by the
following algorithm. The steps take PaymentRequest
- request as input. If the end user inputs or selects a
- card that meets the constraints of BasicCardRequest
- data , the algorithm returns a card as a
+ |request:PaymentRequest| as input. If the end user inputs or selects
+ a card that meets the constraints of BasicCardRequest
+ |data:BasicCardRequest| the algorithm returns a card as a
BasicCardResponse .
- Let networks be
- data ["supportedNetworks "], or an empty list if
- data ["supportedNetworks "] is missing.
+ Let |networks:sequence| be
+ |data|.supportedNetworks , or an empty list if
+ |data|.supportedNetworks is missing.
- Let card be a newly created BasicCardResponse
- dictionary.
+ Let |card:BasicCardResponse| be a newly created
+ BasicCardResponse dictionary.
- Set card ["cardNumber "] to a string of digits of
- length between 10 to 19 items representing the primary account
+ Set |card|.cardNumber to a string of digits of length
+ between 10 to 19 items representing the primary account
number .
While the steps to check if an instrument is supported
- with card , networks returns false, ask the user
- to correct the card's details . Only when the card
- is a supported card , continue.
+ with |card|, |networks| returns false, ask the user to correct the
+ card's details . Only when the |card| is a supported
+ card , continue.
- Set card ["cardholderName "] to the card
- holder's name , or the empty string if the user chooses not to
- provide it.
+ Set |card|.cardholderName to the card holder's
+ name , or the empty string if the user chooses not to provide it.
- Set card ["cardSecurityCode "] to a three or more
- digit string, or the empty string if the user chooses not to provide
- it.
+ Set |card|.cardSecurityCode to a three or more digit
+ string, or the empty string if the user chooses not to provide it.
- Set card ["expiryMonth "] to two-digit string
- ranging from "01
" to "12
", or the empty
- string if the user chooses not to provide it or the card
- doesn't require an expiry month.
+ Set |card|.expiryMonth to two-digit string ranging from
+ "01
" to "12
", or the empty string if the
+ user chooses not to provide it or the card doesn't require an
+ expiry month.
- Set card ["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 card
- doesn't require an expiry year.
+ Set |card|.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 card doesn't require
+ an expiry year.
- Set card ["billingAddress "] to null.
+ Set |card|.billingAddress to null.
- If request .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",
+ Let |redactList:list| be at least « "addressLine",
"organization", "phone", "recipient" ».
- Set card ["billingAddress "] to the result of
- running the steps to Set |card|. billingAddress to the result of running the
+ steps to
create a PaymentAddress
from user-provided
- input with redactList .
+ input with |redactList|.
- Optionally, validate card 's details to make
- sure they adhere to any additional network requirements
- and assist the user in fixing any issues encountered.
+ Optionally, validate |card|'s details to make sure they
+ adhere to any additional network requirements and assist
+ the user in fixing any issues encountered.
- Return card .
+ Return |card|.
@@ -357,46 +356,46 @@
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.
+ steps cause an event to fire in the . 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 PaymentRequest request 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
+ follows. The steps take PaymentRequest |request| 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 PaymentDetailsModifier
s
- apply instead (without the need to run these steps).
+ apply instead (without the need
+ to run these steps).
- Let methodDetails be a newly created
- BasicCardChangeDetails dictionary.
+ Let |methodDetails:BasicCardChangeDetails| be a newly created
+ BasicCardChangeDetails dictionary.
From the supported cards presented to the end user, let
- card be the card the user selects.
+ |card| be the card the user selects.
- Let billingAddress be null.
+ Let |billingAddress:PaymentAddress| be null.
- If request .If |request|. [[\options]] ["requestBillingAddress
"]
is true:
- Let redactList be at least « "addressLine",
+ Let |redactList:list| be at least « "addressLine",
"organization", "phone", "recipient" ».
- The redactList optionally gives user agents the
+ 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.
@@ -407,20 +406,20 @@
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.
+ 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.
- Set billingAddress to the result of running the
- steps to Set |billingAddress| to the result of running the steps to
+
create a PaymentAddress
from user-provided
- input with redactList .
+ input with |redactList|
- Optionally, redact billingAddress .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.
@@ -428,12 +427,19 @@
Set
- methodDetails ["billingAddress "] to
- billingAddress .
+ |methodDetails|.billingAddress to |billingAddress|.
- Run request 's Run |request|s payment method
- changed algorithm with methodDetails and "basic-card".
+ changed algorithm with |methodDetails| and "basic-card".
+
+ Let |networkIdentifier:DOMString| be the network of the
+ selected instrument.
+
+ If updateWith()
+ was called, apply the modifiers using |request| and
+ |networkIdentifier|
+
+
+ Selecting the payment handler
+
+
+
+ In the case where a payment request is made with multiple
+ applicable PaymentMethodData s, 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.
+ await new 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 PaymentRequest
+ |request:PaymentRequest|.
+
+
+ Let |restrictions:BasicCardRequest| be a newly created
+ BasicCardRequest .
+
+ For each pair (DOMString |id| / string
+ |data| of |request|.[[\serializedMethodData]]
+ in reverse order:
+
+ If |id| is not "basic-card"
, continue.
+
+ Let |object:object| be result of JSON-parsing |data|
+
+ If |object| is null
, break.
+
+ Otherwise, set |restrictions:BasicCardRequest| be the result
+ of converting |object| into a
+ BasicCardRequest .
+
+ Break.
+
+
+
+ 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.
+
+
+
+
+
+ Applying the modifiers
+
+
+ The steps to apply the modifiers are given by the
+ following algorithm. It takes a PaymentRequest
+ |request:PaymentRequest| and a string |networkIdentifier:string| that
+ identifies a network :
+
+
+ Let |index:unsigned integer| be the length of
+ |request|.[[\serializedModifierData]]
.
+
+ Let |restrictions:BasicCardRequest| be a newly created
+ BasicCardRequest .
+
+ For each pair (DOMString |id:DOMString| /
+ string |data:string|) of |request|[[\serializedModifierData]]
+ in reverse order:
+
+ Decrement |index| by 1.
+
+ If |id| is not "basic-card ", continue.
+
+ Let |object:object| be result of JSON-parsing |data|
+
+ If |object| is null
, break.
+
+ Let |bcRequest:BasicCardRequest| be the result of converting
+ |object| to BasicCardRequest .
+
+ If |bcRequest|s supportedNetworks is zero length, or
+ supportedNetworks includes |networkIdentifier|
+
+ Set |restriction| to |bcRequest|
+
+ Break.
+
+
+
+
+
+ Let |modifier:PaymentMethodModifier| be the
+ PaymentMethodModifier from |request|.[[\details]] .modifiers at
+ |index|.
+
+ If |modifier|.total
+ is present, update the presented UI with the updated total.
+
+ If |modifier|.additionalDisplayItems
+ is present, update the presented UI with the additional display
+ items.
+
+
+
@@ -592,12 +744,16 @@
- Payment Request
+ Payment Request API
The PaymentAddress
interface, PaymentMethodData
+ dictionary, PaymentMethodModifier
+ dictionary, PaymentRequest
interface, PaymentMethodChangeEvent
@@ -607,6 +763,14 @@
"payment-request#dom-addresserrors">AddressErrors
dictionary are defined in [[payment-request]].
+
+ WebIDL
+
+
+ The DOMString
type is defined in
+ [[WebIDL]].
+