The Basic Card Payment specification describes the data formats used by the PaymentRequest API [PAYMENTREQUESTAPI] to support payment by payment cards such as credit or debit cards.

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 http://www.w3.org/TR/.

The working group maintains a list of all bug reports that the group has not yet addressed. This draft highlights some of the pending issues that are still to be discussed in the working group. No decision has been taken on the outcome of these issues including whether they are valid. Pull requests with proposed specification text for outstanding issues are strongly encouraged.

This specification was derived from a report published previously by the Web Platform Incubator Community Group.

This document was published by the Web Payments Working Group as a First Public Working Draft. If you wish to make comments regarding this document, please send them to public-payments-wg@w3.org (subscribe, archives). All comments are welcome.

Publication as a First Public 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 5 February 2004 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 September 2015 W3C Process Document.

1. Introduction

This section is non-normative.

This specification is a Payment Transaction Message Specification used by the PaymentRequest API [PAYMENTREQUESTAPI] to support payment by payment cards such as credit or debit cards. It is intended to provide compatibility for merchants who currently request card details from customers to ease adoption of the PaymentRequest API.

In the future, merchants should favor payment methods that provide a tokenized response rather than clear text credit card details.

2. Dependencies

This specification relies on several other underlying specifications.

Payment Request Architecture
The terms Payment Method, Payment App, and Payment Transaction Message Specification are defined by the Payment Request Architecture document [PAYMENTARCH].
Payment Request API
The term PaymentRequest constructor is defined by the PaymentRequest API specification [PAYMENTREQUESTAPI].
Payment Method Identifiers
The term Payment Method Identifier is defined by the Payment Method Identifiers specification [METHODIDENTIFIERS].
The IDL in this specification is defined by Web IDL [WEBIDL].

3. Payment Method Identifier

The following payment method identifier strings are supported by the Basic Card Payment data formats.

Identifier StringDescription
visaVisa (Credit, Debit and Electron)
visa/creditVisa Credit
visa/debitVisa Debit
visa/electronVisa Electron
mastercardMasterCard (and EuroCard)
mastercard/creditMasterCard Credit
mastercard/debitMasterCard Debit
amexAmerican Express
dinersDiners Club
unionpay/creditUnionPay Credit
unionpay/debitUnionPay Debit

4. Payment Method Specific Data for the PaymentRequest constructor

This section describes payment method specific data that is supplied as part of the data argument to the PaymentRequest constructor.

There is no payment method specific data used by the PaymentRequest constructor when processing Basic Card Payment methods.

5. Payment Method Response

The BasicCardResponse dictionary contains the response from the PaymentRequest API when a user accepts payment with a Basic Payment Card payment method.

5.1 BasicCardResponse

dictionary BasicCardResponse {
    required DOMString       cardholderName;
    required DOMString       cardNumber;
    required DOMString       expiryMonth;
    required DOMString       expiryYear;
             DOMString       cardSecurityCode;

             BillingAddress? billingAddress;

The BasicCardResponse dictionary contains the following fields:

The cardholderName field contains the cardholder's name as it appears on the card.
The cardNumber field contains the primary account number (PAN) for the payment card.
The expiryMonth field contains a two-digit string for the expiry month of the card in the range 01 to 12.
The expiryYear field contains a two-digit string for the expiry year of the card in the range 00 to 99.
The cardSecurityCode field contains a three or four digit string for the security code of the card (sometimes known as the CVV, CVC, CVN, CVE or CID).
Issue 55: Should the messages support field-level encryption?

There is a requirement for payment apps to be able to return data that is hidden from the payee themselves (perhaps for PCI scope reasons) as they will pass it on to their payment service processor who can then decrypt it and use it.

5.2 BillingAddress

dictionary BillingAddress {
    // [...] fields TBC - most likely the same as shipping address

The BillingAddress dictionary contains the billing address information associated with the payment card.


The fields of the BillingAddress will most likely match those in the shipping address of the PaymentRequest API once those are defined.

Issue 17: complete() should take a string argument not boolean
There is an open issue about what values can be supplied to complete. These may depend on the payment method selected and then Basic Card Payment values would need to be defined in this document.

A. References

A.1 Normative references

Adrian Bateman; Zach Koch; Richard Barnes. Payment Method Identifiers. W3C Editor's Draft. URL: method-identifiers.html
Adrian Bateman; Zach Koch; Richard Barnes. Payment Request Architecture. W3C Editor's Draft. URL: architecture.html
Adrian Bateman; Zach Koch; Richard Barnes. Payment Request API. W3C Editor's Draft. URL: paymentrequest.html
Cameron McCormack; Boris Zbarsky. W3C. WebIDL Level 1. 8 March 2016. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL-1/